Quickstart: REST endpoints

This section shows how to setup and implement a first UM plugin that provides a simple REST API.

Create your first plugin

Creating an empty UM plugin is as simple as creating a directory structure following a specific naming rule and putting a plugin.desc.json file in the right place.

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

Assuming you already have a running UM (version 7.29.0 or later) installed in ~/UM, create a directory named after your chosen package name under ~/UM/cmsbs-conf/cse/plugins/ with a plugin descriptor file in it:

mkdir ~/UM/cmsbs-conf/cse/plugins/de.acme.firststeps
touch ~/UM/cmsbs-conf/cse/plugins/de.acme.firststeps/plugin.desc.json

Edit the newly created plugin descriptor file with your favorite text editor to make it look something like this:

{
    "name": "de.acme.firststeps",
    "title": "First steps",
    "description": "Provides a simple REST API for demonstration purposes",
    "version": "0.9.0",
    "um": ">=7.29.0"
}

Restart your UM instance and visit Tools / Apps to find your new plugin listed among a bunch of vendor supplied plugins. Note, however, that the icon displayed in front of your plugin's title looks broken. We'll fix this later on.

Create your first REST controller

Each REST endpoint you want to provide needs its own controller class with a name following a certain convention. Create and edit a new ES6 file with the following name: ~/UM/cmsbs-conf/cse/plugins/de.acme.firststeps/rest/controllers/ListsController.es6.

class ListsController {
    constructor() {
    }
}

Restart your UM instance and try to run your first GET request against the new REST endpoint from your browser:
http://localhost:8080/cmsbs/rest/de.acme.firststeps.Lists/index

This yields a 404 and the logfile ~/UM/cmsbs-work/sys.log says:

Undefined REST controller class: de.acme.firststeps.ListsController

You have created the new controller class but the UM cannot see it because it is not contained in the expected name space object. Add the following line to the end of your ES6 file:

de.acme.firststeps.ListsController = ListsController;

This puts the class into the namespace object you chose when writing the plugin descriptor file.

Restart your UM instance and try to run the GET request again.

This still yields a 404 and the logfile says:

Undefined REST action method: de.acme.firststeps.ListsController.prototype.index

So the controller class could be found but it does not define an index action method.

Fix this by allowing the index action with the GET verb and adding an empty method named index_GET to your controller:

class ListsController {
    constructor() {
        allowActions(this, 'index_GET');
    }

    index_GET() {
    }
}

...

Reload and you should get an empty page with a status code of 200.

Enable auto-reloading

If you are tired of restarting your UM instance for each and every little code manipulation to take effect, simply add the following line to your ~/UM/cmsbs-conf/cmsbs.properties file and restart one more time:

cmsbs.cse.autoreload = true

From now on CSE scripts will be reloaded automatically as soon as one of the .js or .es6 files changes.

JSON response

Now, make your index action return a static JSON response:

    index_GET() {
        renderJson({
            shoutOut: 'This is a working REST endpoint!'
        }, 200);
    }

You can replace the 200 by whichever status code you want to return.
Include the global params and request variable in your response to make it a little more dynamic:

...
    index_GET() {
        renderJson({
            shoutOut: 'This is a working REST endpoint!',
            params,
            request
        }, 200);
    }
...

Call http://localhost:8080/cmsbs/rest/de.acme.firststeps.Lists/index/aaa/bbb/ccc?a=123&b=456 in your browser and try to identify the additional path components and URL parameters in the request property returned within the response body.