Endpoints

Routes

Each route handler class can contain one or more route handler. A route handler must be a method whose first parameter is an Exchange, which contains all the information about the incoming request.

In addition, a route handler must be provided with the annotation Route, which contains information about the path of the route. The Route annotation can also be present in the class to specify a higher-level route.

import de.craftsblock.craftsnet.api.http.Exchange;
import de.craftsblock.craftsnet.api.http.RequestHandler;
import de.craftsblock.craftsnet.api.http.annotations.Route;

@Route("/v1")
public class MyRoute implements RequestHandler {

    @Route("/hello") // /v1/hello
    public String handle(Exchange exchange) {
        return "Hello, World!";
    }

}

All built-in route filters

Note

Each of the filters can also be present on the handler method itself or on the parent class. Annotations located on the parent class are interpreted as filters that override the default behaviour of the individual handler methods in the class.

Annotation	Description	Since
Domain	A list of domains which the route replies to.	2.3.0
ProcessPriority	The priority of the invocation of the handler.	3.0.1
RequestMethod	A list of http methods that the route is designed for.	2.3.0
RequireBody	A list of bodies the route handler requires to work properly.	3.0.4
RequireContentType	A list of content types which the handler requires to work properly.	3.0.4
RequireCookie	A list of cookie names which the route handler requires to work properly.	3.0.6
RequireHeaders	A list of header names the route handler requires to work properly.	3.0.2
RequireParameter	A list of url request parameters that must be present for the route handler to work properly.	3.0.6

Websockets

Each websocket handler class can contain one or more websocket message handler. A websocket message handler must be a method whose first parameter is an SocketExchange, which contains all the information about the incoming message, client and the websocket server. The second parameter is the message, all available message types are listed here.

In addition, a websocket message handler must be provided with the annotation Socket, which contains information about the path of the websocket. The Socket annotation can also be present in the class to specify a higher-level websocket path.

import de.craftsblock.craftsnet.api.websocket.SocketExchange;
import de.craftsblock.craftsnet.api.websocket.SocketHandler;
import de.craftsblock.craftsnet.api.websocket.annotations.Socket;

public class MyWebsocket implements SocketHandler {

    @Socket("/echo")
    public void handle(SocketExchange exchange, byte[] message) {
        exchange.client().sendMessage(message);
    }

}

All built-in websocket filters

Note

Each of the filters can also be present on the handler method itself or on the parent class. Annotations located on the parent class are interpreted as filters that override the default behaviour of the individual handler methods in the class.

Annotation	Description	Since
Domain	A list of domains which the websocket message handler replies to.	2.3.0
ProcessPriority	The priority of the invocation of the handler.	3.0.1
RequireMessageType	The message type the socket message handler can accept. (May only be TEXT or BINARY)	3.0.5

Message Types

Warning

The message type does not apply a filter for the specific handler. It is just a way to get the desired format faster. If you only want to receive text, please set the appropriate filter with the RequireMessageType annotation

A websocket message handler can receive the follwing message types.

Message Type	2nd Parameter
TEXT	String
TEXT & BINARY	byte[]
TEXT & BINARY	de.craftsblock.craftsnet.utils.ByteBuffer
TEXT & BINARY	de.craftsblock.craftsnet.api.websocket.Frame

Register Endpoints

Your newly created endpoints must be registered using the endpoint registry or using the auto register system.

Auto register system

If you want to register your endpoints using the auto register system, please have a look here.

Manual registration

You can register your endpoints manually in your addon class by using route registry.

@Override
public void onEnable() {
    routeRegistry().register(new MyRoute());
    routeRegistry().register(new MyWebsocket());
}

Dynamic url parameters

ToDo

Transformers

ToDo