Create a Custom Endpoint

Scriptable custom endpoints let you launch arbitrary scripts using the IDM REST URI. For information about how custom endpoints are configured, see Create Custom Endpoints to Launch Scripts.

The example endpoint provided in /path/to/openidm/samples/example-configurations/custom-endpoint illustrates the configuration of a custom endpoint, and the structure of custom endpoint scripts.

The purpose of this custom endpoint is to return a list of variables available to each method used in a script. The scripts show the complete set of methods that can be used. These methods map to the standard HTTP verbs - create, read, update, delete, patch, query, and action. A sample JavaScript and Groovy script is provided.

To run the sample:

Copy the endpoint configuration file (samples/example-configurations/custom-endpoint/conf/endpoint-echo.json) to your project's conf directory.
Copy either the JavaScript file (samples/example-configurations/custom-endpoint/script/echo.js) or Groovy script file (samples/example-configurations/custom-endpoint/script/echo.groovy) to your project's script directory.
Open the endpoint configuration file in a text editor:
```
{
    "file" : "echo.groovy",
    "type" : "groovy",
    "_file" : "echo.js",
    "_type" : "text/javascript",
    ...
}  
```
The configuration file contains a reference to the endpoint scripts. In this case, the JavaScript script is commented out (with an underscore before the file and type properties). If you want to use the JavaScript endpoint script, uncomment these lines and comment out the lines that correspond to the Groovy script in the same way.
Endpoint configuration files can include a context property that specifies the route to the endpoint, for example:
```
"context" : "endpoint/linkedView/*"
```
If no context is specified, the route to the endpoint is taken from the file name, in this case endpoint/echo.

Test each method in succession to return the expected request structure of that method. The following examples show the request structure of the read, create and patch methods. The configuration file has been edited to use the JavaScript file, rather than the Groovy file. The output shown in these examples has been cropped for legibility. For a description of each parameter, see "Custom Endpoint Scripts".

The following command performs a read on the echo endpoint and returns the request structure of a read request:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/endpoint/echo"
{
  "_id": "",
  "method": "read",
  "context": {
    "class": "org.forgerock.http.routing.ApiVersionRouterContext",
    "name": "apiVersionRouter",
    "defaultVersionBehaviour": "LATEST",
    "warningEnabled": false,
    "resourceVersion": "1.0",
    "parent": {
      "class": "org.forgerock.http.routing.UriRouterContext",
      "name": "router",
      ...
    }
  },
  "resourceName": "",
  "parameters": {}
}

The following command performs a query on the echo endpoint and returns the request structure of a query request:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/endpoint/echo?_queryFilter=true"
{
  "result": [
    {
      "method": "query",
      "pageSize": 0,
      "queryFilter": "true",
      "resourceName": "",
      "pagedResultsOffset": 0,
      "pagedResultsCookie": null,
      "parameters": {},
      "content": null,
      "queryId": null
      "content": null,
      "context": {
      ...
      }
    }
  ],
  ...
}

The following command sends a create request to the echo endpoint. No user is actually created. The endpoint script merely returns the request structure of a create request. The content parameter in this case provides the JSON object that was sent with the request:

curl \
--header "X-OpenIDM-Password: openidm-admin" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--data '{
       "userName":"steve",
       "givenName":"Steve",
       "sn":"Carter",
       "telephoneNumber":"0828290289",
       "mail":"scarter@example.com",
       "password":"Passw0rd"
       }' \
--request POST \
"http://localhost:8080/openidm/endpoint/echo?_action=create"
{
  "_id": "",
  "method": "create",
  "resourceName": "",
  "newResourceId": null,
  "parameters": {},
  "content": {
    "userName": "steve",
    "givenName": "Steve",
    "sn": "Carter",
    "telephoneNumber": "0828290289",
    "mail": "scarter@example.com",
    "password": "Passw0rd"
  },
  "context": {
  ...
  }
}

The following command sends a patch request to the echo endpoint.

curl \
--header "X-OpenIDM-Password: openidm-admin" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--data '[
    {
      "operation":"replace",
      "field":"/givenName",
      "value":"Steven"
    }
 ]' \
--request PATCH \
"http://localhost:8080/openidm/endpoint/echo"
{
  "_id": "",
  "method": "patch",
  "resourceName": "",
  "revision": null,
  "patch": [
    {
      "operation": "replace",
      "field": "/givenName",
      "value": "Steven"
    }
  ],
  "parameters": {},
  "context": {
  ...
  }
}