Quickstart: REST endpoints

Goal: Implement a simple REST-Service and expose it via REST Proxy.

You can download the whole Kickstarter-based sample application from our GitLab repository: um-public/tutorial-functional-rest-endpoints

Start a new Kickstarter project

First, choose a Java-style package name for your new plugin – e.g. de.acme.tutorial. (See also ACME Corporation)
Please note that com..., net... and org... denote reserved namespaces and can not be used as top-level package names.

Second, use UM-Kickstarter to begin a new UM project:

umkickstarter -n de.acme.tutorial
cd umkickstarter
gradle setup run

Implement REST controller

Create an .es6 or .mjs file in your plugin’s rest/ folder:

cmsbs-conf/cse/plugins/de.acme.tutorial/rest/api.mjs

/// <reference path="../../../.vscode.js"/>

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

de.acme.tutorialController = new RouterBuilder()
    .get('/hello', (req, res) => {
        res.json({ 
            msg: 'Hello world!',
            params: req.params,
            headers: req.headers,
        });
    })

    .build();

Restart your UM instance:

gradle run

Invoke REST service

Try to invoke the new REST service in your browser:

http://localhost:8080/cmsbs/rest/de.acme.tutorial/hello?a=Hello&b=world

URL mapping

Please note, that de.acme.tutorialController corresponds to the name of your plugin as defined in plugin.desc.json plus the special Controller suffix that tells the backend that this should be exposed as a REST controller.

Setup REST Proxy and expose new endpoint

Create a file named rest-proxy/cmsbs-restproxy.properties that configures the REST Proxy:

cmsbs.resturl=http://localhost:8080/cmsbs/rest

cmsbs.restproxy.limit.controller.whitelist.tut1 = "de.acme.tutorial"

Insert the following cp lines to your build.gradle file:

setup.doLast {
    ...
    
    // UM REST Proxy
    cp('UM/web-integration/cmsbs-restproxy.war', new File(pinuts.um.webappsDir, 'p.war'))
    cp('rest-proxy/cmsbs-restproxy.properties', new File(pinuts.um.serverHome, 'cmsbs-restproxy.properties'))
}

Setup and run your UM instance:

gradle setup run

Your new REST endpoint should now be publicly available via REST proxy:

http://localhost:8080/p/de.acme.tutorial/hello

Next steps

You can now progress to implement more useful endpoints. See also: Functional REST endpoints