authenticating requests

creating your own controller

IMPORTANT

the combination of pluginId and controllerName has to be unique, otherwise a RegisterControllerException is thrown.
take a look at the javadoc in the interfaces and annotations for further information

To write a controller, you need to use some annotations:

The class as @RestController with the api route for this controller.
Every method which is supposed to be a controller method has to use @RequestMapping with the
corresponding HTTP-Method and the endpoint for this specific method.
The endpoints have to start with a leading / and end without a /.
You might need to set the content type header, if you want to have a json representation of your object returned.

@RestController(pluginId = "pluginId", endpoint = "/test")
public class TestController {

    @RequestMapping(method = RequestMethod.GET, endpoint = "/hello")
    public String hello() {
        return "hallo";
    }

    @RequestMapping(method =  RequestMethod.GET, endpoint = "/info")
    public String returnSentInfo(@RequestParam(name = "name") String name) {
        return "received " + name;
    }

    @RequestMapping(method = RequestMethod.POST, endpoint = "/body")
    public String sendBody(@RequestBody String string) {
        return "this is the body " + string;
    }
}

important annotations

`RestController`

Required to mark a class as a controller

`RequestParam`

Retrieve a value for the method as a query param from the request.

`RequestMapping`

Mark a method to be registered to an endpoint. Methods without this annotation are ignored.
Here you can configure some information for the request, like whether or not it should use a token for verification.

`RequestBody`

Retrieve the request body.

`PathParam`

Retrieve a value from the path variable of the request.

The RequestParam can be used like /api/{$pluginId}/{$controller}/{$task}?name=Someone.
The PathParam can be used like /api/{$pluginId}/{$controller}/{$task}/{$PathParam}.

configuring headers

For configuring headers you can use IResponseEntity and its default implementation ResponseEntity to encapsulate your returned value and configure the response headers by using the addHeader(String header, String value) method of IResponseEntity:


 @RequestMapping(method = RequestMethod.GET, endpoint = "headerRequest")
    public IResponseEntity<String> hallo() {
        ResponseEntity<String> stringResponseEntity = new ResponseEntity<>("");
        stringResponseEntity.addHeader("some-header", "GET");
        stringResponseEntity.addHeader("Content-Type", "application/json");
        return stringResponseEntity;
    }

authentication

By default all with RequestMapping annotated methods require a token authentication. The valid tokens can be verified by the administrator.

transferring objects

All data is send as JSON. If you want to send some custom object, you will need to anotate the specific fields you want to be sent as @JsonProperty:

public class DummyObject {
    @JsonProperty
    private String name;
    private int age;

   public DummyObject(String name, int age) {
       this.name = name;
       this.age = age;
   }

   public String getName() {
       return name;
   }
   public void setName(String name) {
       this.name = name;
   }
   public int getAge() {
       return age;
   }
   public void setAge(int age) {
       this.age = age;
   }
}

registering a controller

In order to register the controller you need to inject IRestControllerService and register the controller on this service:

    @Inject
    IRestControllerService restControllerService;

    @Listener
    public void onInitialize(IBotStateEvent.IInitializeEvent event) {
        restControllerService.registerController(TestController.class, new TestController());
    }

configuration

There are two configuration files. One general file for the rest controller configuration and one for the token configuration.

ports

There is the port property in the configuration. (Default is 8723)

default header

You can add headers to the header field:

"headers": {
    "Access-Control-Allow-Origin": "*",
    "Content-Type": "application/json"
  },

CORS

You can enable/disable CORS in the configuration. Additionally you can add there custom header fields only for CORS enabled requests.


"cors": {
    "enabled": true,
    "headers": {
      "Access-Control-Allow-Methods": "POST, PUT, PATCH, OPTIONS",
      "Access-Control-Allow-Origin": "GET, POST, PUT, PATCH",
      "Access-Control-Allow-Headers": "Content-Type"
    }
  }