Custom services

This document describes how to implement custom services using external objects.

These custom services are only available as of version 3.1 and only on the API endpoint. The authentication mechanisms available on this endpoint are described in this document the credentials that needs to be passed to the calls are noted <credentials>.

The calls examples are given using the curl command line tool (that can easily be transposed to any HTTP client tool or API).

Note: the -b cookies.txt -c cookies.txt parameters of the curl calls bellow are required as they allow to use the same server session (identified by the JSESSIONID cookie).

For an application named myapp, the base URL of the custom services is:

http[s]://<host[:<port>]>/myapp/api/ext

It will be noted <base URL> in the rest of the document.

Warning: In production the services endpoint's URL should be restricted only to allowed origins e.g. using URL filtering based on request's origin IP address or similar approaches.

Service implementation

A custom service is just a plain external object (check this document for general principles of external objects).

In particular this external object needs to be granted to the user that will be calling it on the API endpoint.

For a JSON/REST custom service, the implementation of the MyService external object could be something like:

// The function to implement is the display method like for any external object
MyService.display = function(params) {
    // In this example the output is JSON, the MIME type needs to be forced explicitly
    this.setMIMEType(HTTPTool.MIME_TYPE_JSON + "; charset=" + Globals.getPlatformEncoding());
    // Note that if MIME type is left to default (HTML), a this.setDecoration(false) is generally required

    var method = params.getMethod();
    console.log("Call method = " + method);

    var req = params.getJSONObject();
    console.log("Request body = " + req);

    var res = new JSONObject();
    if (method == "POST") {
        if (req != null) {
            res.put("request", req);
            res.put("response", "Hello " + req.optString("name", "Unknown"));
        } else {
            res.put("error", "Call me with a request please !");
        }
    } else {
        res.put("error", "Call me in POST please !");
    }
    return res.toString();
};

Service call

Then the service could be called (using POST method in ths example) like this:

curl <credentials> -b cookies.txt -c cookies.txt -X POST -H "Content-type:application/json" -d @req.json "<base URL>/MyService"

Where, for instance req.json is:

{
    "name": "Bob"
}

The result is then:

{
    "request" : {
        "name": "Bob"
    },
    "response": "Hello Bob!"
}