5.6. Adding Custom Endpoints

You can customize OpenIDM to meet the specific requirements of your deployment by adding your own RESTful endpoints. Endpoints are configured in files named conf/endpoint-name.json, where name generally describes the purpose of the endpoint.

A sample custom endpoint configuration is provided at openidm/samples/customendpoint. The sample includes two files:

conf/endpoint-echo.json, which provides the configuration for the endpoint.
script/echo.js, which is launched when the endpoint is accessed.

The structure of an endpoint configuration file is as follows:

{ 
  "context" : "endpoint/echo", 
  "type" : "text/javascript", 
  "file" : "script/echo.js" 
}
"context"

The URL context under which the endpoint is registered. Currently this must be under endpoint/. An endpoint registered under the context endpoint/echo is addressable over REST at http://localhost:8080/openidm/endpoint/echo and with the internal resource API, for example openidm.read("endpoint/echo").

"type"

The type of implementation. Currently only "text/javascript" is supported.

"source" or "file

The actual script, inline, or a pointer to the file that contains the script. The sample script, (samples/customendpoint/script/echo.js) simply returns the HTTP request when a request is made on that endpoint.

The endpoint script has a request variable available in its scope. The request structure carries all the information about the request, and includes the following properties:

id

The local ID, without the endpoint/ prefix, for example, echo.

method

The requested operation, that is, create, read, update, delete, patch, query or action.

params

The parameters that are passed in. For example, for an HTTP GET with ?param=x, the request contains "params":{"param":"x"}.

parent

Provides the context for the invocation, including headers and security.

Note that the interface for this context is still evolving and may change in a future release.

A script implementation should check and reject requests for methods that it does not support. For example, the following implementation supports only the read method: 

if (request.method == "read") {
    ...
} else {
    throw "Unsupported operation: " + request.method;
}

The final statement in the script is the return value. Unlike for functions, at this global scope there is no return keyword. In the following example, the value of the last statement (x) is returned. 

var x = "Sample return"
functioncall();
x

The following example uses the sample provided in openidm/samples/customendpoint and shows the complete request structure, which is returned by the query. 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/endpoint/echo?param=x"
{
  "type": "resource",
  "uuid": "21c5ddc6-a66e-464e-9fa4-9b777505799e",
  "params": {
    "param": "x"
  },
  "method": "query",
  "parent": {
    "path": "/openidm/endpoint/echo",
    "headers": {
      "Accept": "*/*",
      "User-Agent": "curl/7.21.4 ... OpenSSL/0.9.8r zlib/1.2.5",
      "Authorization": "Basic b3BlbmlkbS1hZG1pbjpvcGVuaWRtLWFkbWlu",
      "Host": "localhost:8080"
    },
    "query": {
      "param": "x"
    },
    "method": "GET",
    "parent": {
      "uuid": "bec97cbf-8618-42f8-a841-9f5f112538e9",
      "parent": null,
      "type": "root"
    },
    "type": "http",
    "uuid": "7fb3e0d9-5f56-4b15-b710-28f2147cf4b4",
    "security": {
      "openidm-roles": [
        "openidm-admin",
        "openidm-authorized"
      ],
      "username": "openidm-admin",
      "userid": {
        "component": "internal/user",
        "id": "openidm-admin"
      }
    }
  },
  "id": "echo"
}

You must protect access to any custom endpoints by configuring the appropriate authorization for those contexts. For more information, see the Authorization section.