02. Defining Endpoints

HttpRequest

HttpRequest is the parent class of all incoming HTTP requests. The package holding this class also has child classes that are specialized for each HTTP request method that the server can support.

HTTP request method	Class name	Fully qualified name
GET	HttpGetRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpGetRequest.java`
POST	HttpPostRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpPostRequest.java`
PUT	HttpPutRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpPutRequest.java`
DELETE	HttpDeleteRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpDeleteRequest.java`
HEAD	HttpHeadRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpHeadRequest.java`
OPTIONS	HttpOptionsRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpOptionsRequest.java`
PATCH	HttpPatchRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpPatchRequest.java`
any*	HttpRequest	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpReq.HttpRequest.java`

Since HttpRequest is the parent class, if you set it as request, you can get any of its child class instance. But it will not be very practical when it comes to usage.

HttpResponse

HttpResponse is the class of response that API user (it means you) return to the client (web browser or something).

Class name	Fully qualified name
HttpResponse	`io.github.lycoriscafe.nexus.http.engine.ReqResManager.httpRes.HttpResponse.java`

Request method annotations

In this library, another bold point is request method annotations. They are the code components that define the endpoints. By annotating classes and methods, the library will get to know there is an endpoint method in this class.

Annotation	Type	Description	Fully qualified name
@HttpEndpoint	Class annotation	Mark a class as a endpoint methods holder	`io.github.lycoriscafe.nexus.http.core.HttpEndpoint.java`
@GET	Method annotation	Mark a method as a `GET` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.GET.java`
@POST	Method annotation	Mark a method as a `POST` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.POST.java`
@PUT	Method annotation	Mark a method as a `PUT` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.PUT.java`
@DELETE	Method annotation	Mark a method as a `DELETE` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.DELETE.java`
@HEAD	Method annotation	Mark a method as a `HEAD` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.HEAD.java`
@OPTIONS	Method annotation	Mark a method as a `OPTIONS` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.OPTIONS.java`
@PATCH	Method annotation	Mark a method as a `PATCH` endpoint	`io.github.lycoriscafe.nexus.http.core.requestMethods.annotations.PATCH.java`

Each of these annotations will call for the target resource URI (simply endpoint link) as the only parameter.

Defining an endpoint

When defining an endpoint method, we have a code of conduct.

Method must be public and static.
Method must use the return type as HttpResponse.
Method must have two parameters. HttpRequest type and HttpResponse respectively.
The class holding the method must be annotated with @HttpEndpoint.

Let's do the code in the package endpoints that created in chapter 01. Let's create a class and name it as SampleEndpoints.java. This is a simple HTTP GET request written using the Nexus-HTTP.

@HttpEndpoint("/")
public class SampleEndpoints {
    @GET("/")
    public static HttpResponse sampleGetEndpoint(HttpGetRequest request,
                                                 HttpResponse response) {
        return response;
    }
}

When you navigate to the web page http://localhost:80, there will be a blank page with no content on it. It means the request you made has gone through your endpoint method successfully.