To create a REST API endpoint using the new ApiRouter, create an .es6 file in your plugin's rest/ folder, e.g. "UM/cmsbs-conf/cse/plugins/de.mycompany.restdemo/rest/demo.es6":

import { RouterBuilder } from '@de.pinuts.apirouter/shared/routing.es6';

class DocumentController {
    list() {
        // Will be called when requesting GET <http://localhost:8080/cmsbs/rest/de.mycompany.restdemo.api/document>
    }

    show() {
        // Will be called when requesting GET <http://localhost:8080/cmsbs/rest/de.mycompany.restdemo.api/document/123>
        UM.dump(params, 'params:');
    }

    update() {
        // Will be called when requesting PUT <http://localhost:8080/cmsbs/rest/de.mycompany.restdemo.api/document/123>
        UM.dump(params, 'params:');
    }

    create() {
        // Will be called when requesting POST <http://localhost:8080/cmsbs/rest/de.mycompany.restdemo.api/document>
        UM.dump(params, 'params:');
    }

    delete() {
        // Will be called when requesting DELETE <http://localhost:8080/cmsbs/rest/de.mycompany.restdemo.api/document/123>
        UM.dump(params, 'params:');
    }

    beforeInterceptor() {
        // Add your custom authorization code here.

        return true;
    }
}

const routerBuilder = new RouterBuilder()
    .protectFromForgery()
    .protectFromCaching()
    .allowCors()
    .handlePreflightRequests()
    .get('/document', DocumentController, 'list')
    .get('/document/:id', DocumentController, 'show')
    .put('/document/:id', DocumentController, 'update')
    .post('/document', DocumentController, 'create')
    .delete('/document/:id', DocumentController, 'delete');

de.mycompany.restdemo.apiController = routerBuilder.build();

protectFromForgery

protectFromForgery() tells the Router to accept POST, PUT and DELETE requests only if the request header X-CSRF-Token is provided and contains the correct CSRF Token.
The CSRF Token will be returned with every request as the response header named X-CSRF-Token to the client.

protectFromCaching

Sets the Cache-Control header appropriately to prevent client and reverse proxies from caching any of the responses.

allowCors

allowCors() tells the Router to send Access-Control-Allow headers for POST, PUT and DELETE requests.

The Access-Control-Allow-Origin header is set to the URL from the global CORS plugin instance that matches the given Origin header. If at least one such URL is given in the CORS plugin, the request will be denied (status 403) if none of the URLs matches the Origin.

handlePreflightRequests

handlePreflightRequests() tells the Router to respond to all OPTIONS (=preflight) requests by setting the appropriate Access-Control-Allow headers according to the global default settings defined in the CORS app instance.
This is necessary to allow POST, PUT and DELETE requests in a Cross Origin situation.

beforeInterceptor

If a method named beforeInterceptor is present in the Controller class, the request will only be fulfilled if this method returns true.
This method is usually a good place to implement you Authentication logic.

Consuming a REST API

REST APIs that make use of the allowCors() function require a special request header to be sent with every non-GET request:

• X-CSRF-Safe or

• X-CSRF-Token if protectFromForgery() has also been called.

This is true no matter what kind of client is used to perform the request.

If the client is a standard web browser, the presence of either of theses two headers proves that the request has not been triggered by posting a simple POST form, but rather is an XHR request, which ensures that CORS rules apply and Cross Site Request Forgery can be prohibited.