<commit_before># Web-API API

The Web-API API offers an interface for other plugins to interact with the Web-API. This allows
other plugins to provide their own endpoints for data without much effort.


## Table of Contents
1. [Servlets](#servlets)
    1. [Example](#servlet-example)
1. [Endpoints](#endpoints)
    1. [Example](#endpoint-example)
1. [Requests](#requests)
1. [Responses](#responses)


<a name="servlets"></a>
## Servlets
Servlets are a collection of routes. This allows you to easily group all data that belongs together.

At runtime the Web-API will create an instance of your servlet and use it to server the routes
that you specified.

> Note that your servlet is re-initialized (a new class instance is created) when the Web-API 
performs a reload (e.g. through `sponge plugins reload`), so any initialization that your routes
require should be handled in your constructor.

Your servlet class needs to extend `WebAPIBaseServlet`, which is the base servlet that provides
some functionality for your servlet to use.

You must also add the `@WebAPIServlet(basePath = "")` annotation to the class. This annotation
tells the Web-API that your class is indeed a valid servlet, and which base route to use. 

- The `basePath` specifies at which path your servlet will be available, and all the other 
routes in your servlet will be relative to this route.The `basePath` does **not** require any slashes `/` and may **not** contain any path parameters (see below).

<a name="servlet-example"></a>
### Example

```java<commit_msg>docs(api): Update documentation for API<commit_after># Web-API API

The Web-API API offers an interface for other plugins to interact with the Web-API. This allows
other plugins to provide their own endpoints for data without much effort.


## Table of Contents
1. [Setup](#setup)
1. [Servlets](#servlets)
    1. [Example](#servlet-example)
1. [Endpoints](#endpoints)
    1. [Example](#endpoint-example)
1. [Requests](#requests)
1. [Responses](#responses)


<a name="setup"></a>
## Setup

> You have to register any servlets you create with the WebAPI

The easiest way to do this is to use `WebAPIAPI.getServletService()`, which will return an optional
containing the ServletService. If the optional is empty than the WebAPI plugin is not present or 
loaded on the server. If the ServletService is present you can use 
`service.registerServlet(Class<? extends WebAPIBaseServlet> servlet)` to register your servlet class
with the WebAPI.
```java
public void onInitialization(GameInitializationEvent event) {
    ...
    
    Optional<IServletService> optSrv = WebAPIAPI.getServletService();
    if (optSrv.isPresent()) {
        IServletService srv = optSrv.get();
        srv.registerServlet(MyServlet.class);
    }
    
    ...
}
```

> This should be done in the initialization phase of your plugin, before the server starts!


<a name="servlets"></a>
## Servlets
Servlets are a collection of routes. This allows you to easily group all data that belongs together.

At runtime the Web-API will create an instance of your servlet and use it to server the routes
that you specified.

> Note that your servlet is re-initialized (a new class instance is created) when the Web-API 
performs a reload (e.g. through `sponge plugins reload`), so any initialization that your routes
require should be handled in your constructor.

Your servlet class needs to extend `WebAPIBaseServlet`, which is the base servlet that provides
some functionality for your servlet to use.

You must also add the `@WebAPIServlet(basePath = "")` annotation to the class. This annotation
tells the Web-API that your class is indeed a valid servlet, and which base route to use. 

- The `basePath` specifies at which path your servlet will be available, and all the other 
routes in your servlet will be relative to this route.The `basePath` does **not** require any slashes `/` and may **not** contain any path parameters (see below).

Servlets may define a `public static void onRegister()` method which will get called by the WebAPI
when the servlet is registered. This is only done once, even if the user reloads the plugins
on the server. This is the best place to register any custom serializers that your servlets uses:
```java
public static void onRegister() {
    JsonService json = WebAPI.getJsonService();
    json.registerSerializer(MyData.class, MyDataSerializer.class);
}
```


<a name="servlet-example"></a>
### Example

```java
{'fraction_non_alphanumeric': 0.08213644524236983, 'fraction_numerical': 0.0029174147217235187, 'mean_word_length': 4.382850241545894, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2517035', 'n_tokens_mistral': 1232, 'n_tokens_neox': 1195, 'n_words': 597}