REST API Reference

Representational State Transfer (REST) is a software architecture style for exposing resources, using the technologies and protocols of the World Wide Web. REST describes how distributed data objects, or resources, can be defined and addressed. OpenIDM provides a RESTful API for accessing managed objects, system objects, workflows, and some elements of the system configuration.

The Open Identity Platform implementation of REST, known as commons REST (CREST), defines an API intended for common use across all Open Identity Platform products. CREST is a framework used to access various web resources, and for writing to RESTful resource providers (servers).

CREST is intended to support the following types of operations, described in detail in "Supported Operations": Create, Read, Update, Delete, Action, and Query.

The examples in this chapter show REST requests to OpenIDM over the regular (http) port.

Open Identity Platform Community defines a JSON Resource core library, as a common framework to implement RESTful APIs. That core library includes two components:

json-resource

A Maven module that provides core interfaces such as Connections, Requests, and Request Handlers.

json-resource-servlet

Provides J2EE servlet integration. Defines a common HTTP-based REST API for interacting with JSON resources.

You can examine the libraries associated with Open Identity Platform REST at https://github.com/OpenIdentityPlatform/commons/tree/master/commons/rest.

URI Scheme

The URI scheme for accessing a managed object follows this convention, assuming the OpenIDM web application was deployed at /openidm.

/openidm/managed/type/id

Similar schemes exist for URIs associated with all but system objects. For more information, see "Understanding the Access Configuration Script (access.js)".

The URI scheme for accessing a system object follows this convention:

/openidm/system/resource-name/type/id

An example of a system object in an LDAP repository might be:

/openidm/system/ldap/account/07b46858-56eb-457c-b935-cfe6ddf769c7

Note that for LDAP resources, you should not map the LDAP dn to the OpenIDM uidAttribute (_id). The attribute that is used for the _id should be immutable. You should therefore map the LDAP entryUUID operational attribute to the OpenIDM _id, as shown in the following excerpt of the provisioner configuration file:

...
"uidAttribute" : "entryUUID",
...

Object Identifiers

Every managed and system object has an identifier (expressed as id in the URI scheme) that is used to address the object through the REST API. The REST API allows for client-generated and server-generated identifiers, through PUT and POST methods. The default server-generated identifier type is a UUID. If you create an object by using POST, a server-assigned ID is generated in the form of a UUID. If you create an object by using PUT, the client assigns the ID in whatever format you specify.

Most of the examples in this guide use client-assigned IDs, as it makes the examples easier to read.

For more information on whether to use PUT or POST to create managed objects, see Should You Use PUT or POST to Create a Managed Object?.

Content Negotiation

The REST API fully supports negotiation of content representation through the Accept HTTP header. Currently, the supported content type is JSON. When you send a JSON payload, you must include the following header:

Accept: application/json

In a REST call (using the curl command, for example), you would include the following option to specify the noted header:

--header "Content-Type: application/json"

You can also specify the default UTF-8 character set as follows:

--header "Content-Type: application/json;charset=utf-8"

The application/json content type is not needed when the REST call does not send a JSON payload.

Supported Operations

CREST supports several types of operations for communication with web servers.

The following request parameters can be used in conjunction with the supported operations.

_fields

The _fields parameter can be used to return multiple common attributes.

For example, you can use GET to read specific attributes for a user as follows:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET
 "http://localhost:8080/openidm/managed/user/james?_fields=userName,mail"
 {
  "mail": "james@example.com",
  "userName": "james"
 }
_prettyPrint=[true,false]

If _prettyPrint=true, the HttpServlet formats the response, in a fashion similar to the JSON parser known as jq.

For example, adding _prettyPrint=true to the end of a query-all-ids request formats the output in the following manner:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/managed/user?_queryId=query-all-ids&_prettyPrint=true"
{
 "result" : [ {
   "_id" : "bjensen",
   "_rev" : "0"
 }, {
   "_id" : "scarter",
   "_rev" : "0"
 }, {
   "_id" : "jberg",
   "_rev" : "0"
 } ],
 "resultCount" : 3,
 "pagedResultsCookie" : null,
 "remainingPagedResults" : -1
}

Note that most command-line examples in this guide do not show this parameter, although the output in the examples is formatted for readability.

Creating an Object

Objects can be created with two different HTTP operations: POST and PUT.

To create an object with a server-assigned ID, use the POST operation with the create action. For example:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
    "userName":"mike",
    "sn":"Smith",
    "givenName":"Mike",
    "mail": "mike@example.com",
    "telephoneNumber": "082082082",
    "password":"Passw0rd"
 }'
 "http://localhost:8080/openidm/managed/user?_action=create"
{
  "userName": "mike",
  ...
  "_rev": "1",
  "_id": "a5bed4d7-99d4-41c4-8d64-49493b48a920",
  ...
}

To create an object with a client-assigned ID, use a PUT request, with the If-None-Match: * header. Specify the ID as part of the URL, for example:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --request PUT \
 --data '{
    "userName":"james",
    "sn":"Berg",
    "givenName":"James",
    "mail": "james@example.com",
    "telephoneNumber": "082082082",
    "password":"Passw0rd"
    }' \
 "http://localhost:8080/openidm/managed/user/james"
{
  "userName": "james",
  ...
  "_rev": "1",
  ...
  "_id": "james",
  ...
}

Reading an Object

To read the contents of an object, use the GET operation, specifying the object ID. For example:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/system/ldap/account/fc252fd9-b982-3ed6-b42a-c76d2546312c"
{
    "givenName": "Barbara",
    "telephoneNumber": "1-360-229-7105",
    "dn": "uid=bjensen,ou=People,dc=example,dc=com",
    "description": "Created for OpenIDM",
    "mail": "bjensen@example.com",
    "ldapGroups": [
        "cn=openidm2,ou=Groups,dc=example,dc=com"
    ],
    "cn": "Barbara Jensen",
    "uid": "bjensen",
    "sn": "Jensen",
    "_id": "fc252fd9-b982-3ed6-b42a-c76d2546312c"
}

Updating an Object

An update replaces some or all of the contents of an existing object. Any object can be updated over REST with a PUT request. Managed objects and some system objects can also be updated with a PATCH request.

To update a managed or system object with a PUT request, specify the object ID in the URL. For managed objects, you must include the complete object in the JSON payload. You can also include an optional If-Match conditional header. If no conditional header is specified, a default of If-Match: "*" is applied.

The following example updates Joe Smith’s telephone number, and supplies his complete managed user object, with the updated value, in the JSON payload:

$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "If-Match: *" \
 --request PUT \
 --data '{
  "userName":"joe",
  "givenName":"joe",
  "sn":"smith",
  "mail":"joe@example.com",
  "telephoneNumber":"555-123-457",
  "password":"Passw0rd",
  "description":"This is Joe Smith's description"
  }' \
 "http://localhost:8080/openidm/managed/user/07b46858-56eb-457c-b935-cfe6ddf769c7"

A PATCH request can add, remove, replace, or increment an attribute value. A replace operation replaces an existing value, or adds a value if no value exists.

When you update a managed or system object with a PATCH request, you can include the optional If-Match conditional header. If no conditional header is specified, a default of If-Match: "*" is applied.

The following example shows a patch request that updates a multi-valued attribute by adding a new value. Note the dash - character appended to the field name, which specifies that the value provided should be added to the existing values. If the dash character is omitted, the provided value replaces the existing values of that field.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --request PATCH \
 --data '[
    {
        "operation": "add",
        "field": "/roles/-",
        "value": "managed/role/ldap"

    }
]' \
 "http://localhost:8080/openidm/managed/user/bjensen"

Deleting an Object

A delete request is similar to an update request, and can optionally include the HTTP If-Match header. To delete an object, specify its ID in the request, for example:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request DELETE \
 "http://localhost:8080/openidm/system/ldap/account/e81c7f15-2e6d-4c3c-8005-890101070dd9"
{
    "_id": "e81c7f15-2e6d-4c3c-8005-890101070dd9"
}

Querying Resources

Resources can be queried using the GET method, with one of the following query parameters: For queries on managed objects:

  • _queryId for arbitrary predefined, parameterized queries

  • _queryFilter for arbitrary filters, in common filter notation

  • _queryExpression for client-supplied queries, in native query format

For queries on system objects:

  • _queryId=query-all-ids (the only supported predefined query)

  • _queryFilter for arbitrary filters, in common filter notation

For more information on queries, see "Constructing Queries".

Conditional Operations

The REST API supports conditional operations through the use of the ETag, If-Match and If-None-Match HTTP headers. The use of HTTP conditional operations is the basis of OpenIDM’s optimistic concurrency control system. Clients should make requests conditional in order to prevent inadvertent modification of the wrong version of an object. If no conditional header is specified, a default of If-Match: * is applied.

Supported Methods

The managed object API uses standard HTTP methods to access managed objects.

GET

Retrieves a managed object in OpenIDM.

Example Request

GET /openidm/managed/user/bdd793f8
...

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache
Vary: Accept-Encoding, User-Agent
Set-Cookie: session-jwt=2sadf... afd5;Path=/
Expires: Thu, 01 Jan 2015 00:00:00 GMT
Content-Length: 1230
Server: Jetty(8.y.z-SNAPSHOT)
...

[JSON representation of the managed object]
PUT

Creates or updates a managed object.

If you include the If-None-Match header, its value must be . In this case, the request creates the object if it does not exist and fails if the object does exist. If you include the If-None-Match header with any value other than , the server returns an HTTP 400 Bad Request error. For example, creating an object with If-None-Match: revision returns a bad request error. If you do not include If-None-Match: *, the request creates the object if it does not exist, and updates the object if it does exist.

Example Request: Creating a new object

PUT /openidm/managed/user/5752c0fd9509
Content-Type: application/json
Content-Length: 123
If-None-Match: *
...

[JSON representation of the managed object to create]

Example Response: Creating a new object (success)

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 45
ETag: "0"
...

[JSON representation containing metadata (underscore-prefixed) properties]

Example Response: Creating or updating an object with the If-None-Match header set to something other than *

HTTP/1.1 400 "Bad Request
Content-Type: application/json
Content-Length: 83
...

[JSON representation of error]

Example Request: Updating an existing object

PUT /openidm/managed/user/5752c0fd9509
Content-Type: application/json
Content-Length: 123
If-Match: "1"
...

[JSON representation of managed object to update]

Example Response: Updating an existing object (success)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 45
ETag: "2"
...

[JSON representation of updated object]

Example Response: Updating an existing object when no version is supplied

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 89
ETag: "3"
...

[JSON representation of updated object]

Example Response: Updating an existing object when an invalid version is supplied

HTTP/1.1 412 Precondition Required
Content-Type: application/json
Content-Length: 89
...

[JSON representation of error]

Example Response: Updating an existing object with If-Match: *

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 45
ETag: "0"
...
[JSON representation of updated object]
Should You Use PUT or POST to Create a Managed Object?

You can use PUT and POST to create managed objects. To create a managed object with a PUT, you would include the _id in the request. If you create a managed object with a POST, the server assigns the _id in the form of a UUID.

In some cases, you may want to use PUT, as POST is not idempotent. If you can specify the _id to assign to the object, use PUT.

Alternatively, POST generates a server-assigned ID in the form of a UUID. In some cases, you may prefer to use UUIDs in production, as a POST can generate them easily in clustered environments.
POST

The POST method enables you to perform arbitrary actions on managed objects. The _action query parameter defines the action to be performed.

The create action is used to create a managed object. Because POST is neither safe nor idempotent, PUT is the preferred method of creating managed objects, and should be used if the client knows what identifier it wants to assign the object. The response contains the server-generated _id of the newly created managed object.

The POST method create optionally accepts an _id query parameter to specify the identifier to give the newly created object. If an _id is not provided, the server selects its own identifier.

The patch action updates one or more attributes of a managed object, without replacing the entire object.

Example Create Request

POST /openidm/managed/user?_action=create
Content-Type: application/json;charset=UTF-8
Content-Length: 123
...

[JSON representation of the managed object to create]

Example Response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache
Location: https://Some_URI
...

[JSON representation containing metadata (underscore-prefixed) properties]

Example Response (success)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache
Set-Cookie: session-jwt=yAiYWxnIjogI;Path=/
...

Example Response: Updating an existing object when an invalid version is supplied

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
Content-Length: 89
...

[JSON representation of error]
DELETE

Deletes a managed object.

Example Request

DELETE /openidm/managed/user/c3471805b60f
If-Match: "0"
...

Example Response (success)

HTTP/1.1 200 OK
Content-Length: 405
Content-Type: application/json;charset=UTF-8
Etag: "4"
...

[JSON representation of the managed object that was deleted]

Example Response: Deleting an existing object when no version is supplied

HTTP/1.1 200 OK
Content-Length: 405
Content-Type: application/json;charset=UTF-8
Etag: "4"
...

[JSON representation of the managed object that was deleted]

Example Response: Deleting an existing object when an invalid version is supplied

HTTP/1.1 412 Precondition Failed
Content-Type: application/json;charset=UTF-8
Content-Length: 89
...

[JSON representation of error]
PATCH

Performs a partial modification of a managed or system object.

Example Request

PATCH /openidm/managed/user/5752c0fd9509
Content-Type: application/patch+json
Content-Length: 456
If-Match: "0"
...

[JSON representation of patch document to apply]

Example Response (success)

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=1kke440cyv1vivbrid6ljso7b;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=UTF-8
ETag: "1"
...
{"_id":"5752c0fd9509","_rev":"2"}

Updating an existing object when no version is supplied (version conflict)

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Content-Length: 89
...

[JSON representation of error]

Example Response: Updating an existing object when an invalid version is supplied (version conflict)

HTTP/1.1 412 Precondition Required
Content-Type: application/json;charset=UTF-8
Content-Length: 89
...

[JSON representation of error]

REST Endpoints and Sample Commands

This section describes the OpenIDM REST endpoints and provides a number of sample commands that show the interaction with the REST interface.

Managing the Server Configuration Over REST

OpenIDM stores configuration objects in the repository, and exposes them under the context path /openidm/config. Single instance configuration objects are exposed under /openidm/config/object-name.

Multiple instance configuration objects are exposed under /openidm/config/object-name/instance-name. The following table outlines these configuration objects and how they can be accessed through the REST interface.

URI

HTTP Operation

Description

/openidm/config

GET

Returns a list of configuration objects

/openidm/config/audit

GET

Returns the current logging configuration

/openidm/config/provisioner.openicf/provisioner-name

GET

Returns the configuration of the specified connector

/openidm/config/router

PUT

Changes the router configuration. Modifications are provided with the --data option, in JSON format.

/openidm/config/object

PATCH

Changes one or more fields of the specified configuration object. Modifications are provided as a JSON array of patch operations.

/openidm/config/object

DELETE

Deletes the specified configuration object.

OpenIDM supports REST mappings for create, read, update, query, and delete of configuration objects.

For an example that displays the current configuration, the current logging configuration, the configuration with an XML connector provisioner, and how the configuration can be modified over the router, see "Configuring OpenIDM Over REST".

One entry is returned for each configuration object. To obtain additional information on the configuration object, include its pid or _id in the URL. The following example displays configuration information on the sync object, based on OpenIDM using Sample 1.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/config/sync"
{
  "mappings": [ {
    "target" : "managed/user",
    "correlationQuery" : {
      "type" : "text/javascript",
      "source" : "var query = {'_queryId' : 'for-userName', 'uid' : source.name};query;"
    },
    "properties" : [ {
      "target" : "_id",
      "source" : "_id"
    }, {
      "target" : "description",
      "source" : "description"
    }, {
      "target" : "givenName",
      "source" : "firstname"
    }, {
      "target" : "mail",
      "source" : "email"
    }, {
...

Managing Users Over REST

User objects are stored in the repository and are exposed under the context path /managed/user. Many examples of REST calls related to this context path exist throughout this document. The following table lists available functionality associated with the /managed/user context path.

URI HTTP Operation Description

/openidm/managed/user?_queryId=query-all-ids

GET

List the IDs of all the managed users in the repository

/openidm/managed/user?_queryId=query-all

GET

List all info for the managed users in the repository

/openidm/managed/user?_queryFilter=filter

GET

Query the managed user object with the defined filter.

/openidm/managed/user/_id

GET

Retrieve the JSON representation of a specific user

/openidm/managed/user/_id

PUT

Create a new user

/openidm/managed/user/_id

PUT

Update a user entry (replaces the entire entry)

/openidm/managed/user?_action=create

POST

Create a new user

/openidm/managed/user?_action=patch&_queryId=for-userName&uid=userName

POST

Update a user (can be used to replace the value of one or more existing attributes)

/openidm/managed/user/_id

PATCH

Update specified fields of a user entry

/openidm/managed/user/_id

DELETE

Delete a user entry

The following example retrieves the JSON representation of all users stored in the internal repository.

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryId=query-all-ids"

The following two examples perform a query on the repository for managed users for a user named smith.

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
 "http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+%22smith%22"

For this second example, note the use of single quotes around the URL, to avoid conflicts with the double quotes around the user named smith. Be aware, the _queryFilter requires double quotes (or the URL encoded equivalent, %22,) around the search term.

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
'http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+"smith"'

The following example retrieves the JSON representation of a specified user.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/managed/user/user_id"

To add a user without a specified ID, see "Adding Users Over REST" in the Samples Guide.

The following example adds a user with a specific user ID.

$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "If-None-Match: *" \
 --request PUT \
 --data '{
    "userName":"james",
    "sn":"Berg",
    "givenName":"James",
    "mail": "james@example.com",
    "telephoneNumber": "082082082",
    "password":"Passw0rd"
  }' \
"http://localhost:8080/openidm/managed/user/james"

The following example checks whether a user exists, then updates the user entry. The command replaces the telephone number with the new data provided in the request body.

$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 --data '[{
  "operation":"replace",
  "field":"/telephoneNumber",
  "value":"1234567"
  }]' \
  "http://localhost:8080/openidm/managed/user?_action=patch&_queryId=for-userName&uid=id"

Managing System Objects Over REST

System objects, that is, objects that are stored in remote systems, are exposed under the /openidm/system context. OpenIDM provides access to system objects over REST, as listed in the following table.

URI HTTP Operation Description

/openidm/system?_action=action-name

POST

_action=availableConnectors returns a list of the connectors that are available in openidm/connectors or in openidm/bundle.

_action=createCoreConfig takes the supplied connector reference (connectorRef) and adds the configuration properties required for that connector. This generates a core connector configuration that you can use to create a full configuration with the createFullConfig action.

_action=createFullConfig generates a complete connector configuration, using the configuration properties from the createCoreConfig action, and retrieving the object types and operation options from the resource, to complete the configuration.

_action=test returns a list of all remote systems, with their status, and supported object types.

_action=testConfig validates the connector configuration provided in the POST body.

_action=liveSync triggers a liveSync operation on the specified source object.

_action=authenticate authenticates to the specified system with the credentials provided.

/openidm/system/system-name?_action=action-name

POST

_action=test tests the status of the specified system.

/openidm/system/system-name/system-object?_action=action-name

POST

_action=liveSync triggers a liveSync operation on the specified system object.

_action=script runs the specified script on the system object.

_action=authenticate authenticates to the specified system object, with the provided credentials.

_action=create creates a new system object.

/openidm/system/system-name/system-object?_queryId=query-all-ids

GET

Lists all IDs related to the specified system object, such as users, and groups.

/openidm/system/system-name/system-object?_queryFilter=filter

GET

Lists the item(s) associated with the query filter.

/openidm/system/system-name/system-object/id

PUT

Creates a system object, or updates the system object, if it exists (replaces the entire object).

/openidm/system/system-name/system-object/id

PATCH

Updates the specified fields of a system object

/openidm/system/system-name/system-object/id

DELETE

Deletes a system object

When you create a system object with a PUT request (that is, specifying a client-assigned ID), you should specify the ID in the URL only and not in the JSON payload. If you specify a different ID in the URL and in the JSON payload, the request will fail, with an error similar to the following:

{
    "code":500,
    "reason":"Internal Server Error",
    "message":"The uid attribute is not single value attribute."
}

A POST request with a patch action is not currently supported on system objects. To patch a system object, you must send a PATCH request.
Returning a list of the available connector configurations
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system?_action=availableConnectors"
Returning a list of remote systems, and their status
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system?_action=test"
[
  {
    "ok": true,
    "displayName": "LDAP Connector",
    "connectorRef": {
      "bundleVersion" : "[1.4.0.0,2)",
      "bundleName" : "org.openidentityplatform.openicf.connectors.ldap-connector",
      "connectorName" : "org.identityconnectors.ldap.LdapConnector"
    },
    "objectTypes": [
      "__ALL__",
      "group",
      "account"
    ],
    "config": "config/provisioner.openicf/ldap",
    "enabled": true,
    "name": "ldap"
  }
]
Two options for running a liveSync operation on a specified system object
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system?_action=liveSync&source=system/ldap/account"
{
  "_rev": "1",
  "_id": "SYSTEMLDAPACCOUNT",
  "connectorData": {
    "nativeType": "integer",
    "syncToken": 0
  }
}
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system/ldap/account?_action=liveSync"

{
  "_rev": "2",
  "_id": "SYSTEMLDAPACCOUNT",
  "connectorData": {
    "nativeType": "integer",
    "syncToken": 0
  }
}
Running a script on a system object
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system/ldap/account?_action=script&_scriptId=addUser"
Authenticating to a system object
$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system/ldap/account?_action=authenticate&username=bjensen&password=Passw0rd"
{
  "_id": "fc252fd9-b982-3ed6-b42a-c76d2546312c"
}
Creating a new system object
$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --data '{
    "cn":"James Smith",
    "dn":"uid=jsmith,ou=people,dc=example,dc=com",
    "uid":"jsmith",
    "sn":"Smith",
    "givenName":"James",
    "mail": "jsmith@example.com",
    "description":"Created by OpenIDM REST"}' \
 --request POST \
 "http://localhost:8080/openidm/system/ldap/account?_action=create"
{
    "telephoneNumber":null,
    "description":"Created by OpenIDM REST",
    "mail":"jsmith@example.com",
    "givenName":"James",
    "cn":"James Smith",
    "dn":"uid=jsmith,ou=people,dc=example,dc=com",
    "uid":"jsmith",
    "ldapGroups":[],
    "sn":"Smith",
    "_id":"07b46858-56eb-457c-b935-cfe6ddf769c7"
}
Renaming a system object

You can rename a system object simply by supplying a new naming attribute value in a PUT request. The PUT request replaces the entire object. The naming attribute depends on the external resource.

The following example renames an object on an LDAP server, by changing the DN of the LDAP object (effectively performing a modDN operation on that object).

The example renames the user created in the previous example.

$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "If-Match: *" \
 --data '{
    "cn":"James Smith",
    "dn":"uid=jimmysmith,ou=people,dc=example,dc=com",
    "uid":"jimmysmith",
    "sn":"Smith",
    "givenName":"James",
    "mail": "jsmith@example.com"}' \
 --request PUT \
 "http://localhost:8080/openidm/system/ldap/account/07b46858-56eb-457c-b935-cfe6ddf769c7"
{
  "mail":"jsmith@example.com",
  "cn":"James Smith",
  "sn":"Smith",
  "dn":"uid=jimmysmith,ou=people,dc=example,dc=com",
  "ldapGroups":[],
  "telephoneNumber":null,
  "description":"Created by OpenIDM REST",
  "givenName":"James",
  "uid":"jimmysmith",
  "_id":"07b46858-56eb-457c-b935-cfe6ddf769c7"
}
List the IDs associated with a specific system object
$ curl \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/system/ldap/account?_queryId=query-all-ids"
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 3,
  "result": [
        {
           "dn": "uid=jdoe,ou=People,dc=example,dc=com",
           "_id": "1ff2e78f-4c4c-300c-b8f7-c2ab160061e0"
       },
       {
           "dn": "uid=bjensen,ou=People,dc=example,dc=com",
           "_id": "fc252fd9-b982-3ed6-b42a-c76d2546312c"
       },
       {
           "dn": "uid=jimmysmith,ou=people,dc=example,dc=com",
           "_id": "07b46858-56eb-457c-b935-cfe6ddf769c7"
       }
  ]
}

Managing Workflows Over REST

Workflow objects are exposed under the /openidm/workflow context. OpenIDM provides access to the workflow module over REST, as listed in the following table.

URI HTTP Operation Description

/openidm/workflow/processdefinition?_queryId=id

GET

Lists workflow definitions based on filtering criteria

/openidm/workflow/processdefinition/id

GET

Returns detailed information about the specified process definition

/openidm/workflow/processinstance?_queryId=query-all-ids

GET

Lists the available running workflows, by their ID

/openidm/workflow/processinstance/id

GET

Provides detailed information of a running process instance

/openidm/workflow/processinstance/history?_queryId=query-all-ids

GET

Lists running and completed workflows, by their ID

/openidm/workflow/processdefinition/id/taskdefinition

GET

Returns detailed information about the task definition, when you include an id or a query for all IDs, ?_queryId=query-all-ids

/openidm/workflow/taskinstance?_queryId=query-all-ids

GET

Lists all active tasks

/openidm/workflow/taskinstance?_queryId=filteredQuery&filter

GET

Lists the tasks according to the specified filter

/openidm/workflow/processinstance?_action=create

POST

Start a new workflow. Parameters are included in the request body.

/openidm/workflow/taskinstance/id

PUT

Update task data

/openidm/workflow/processinstance/id

DELETE

Stops a process instance

/openidm/workflow/taskinstance/id?_action=claim

POST

Claim or complete a task. Parameters are included in the request body. Specifically for user tasks, a user can claim a specific task, which will then be assigned to that user.

The following examples list the defined workflows. For a workflow to appear in this list, the corresponding workflow definition must be in the openidm/workflow directory.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/workflow/processdefinition?_queryId=query-all-ids"

Depending on the defined workflows, the output will be something like the following:

{
"result":[ {
     "tenantId" : "",
     "candidateStarterGroupIdExpressions" : [ ],
     "candidateStarterUserIdExpressions" : [ ],
     "participantProcess" : null,
...
 } ],
     "resultCount" : 1,
     "pagedResultsCookie" : null,
     "remainingPagedResults" : -1
}

The following example invokes a workflow named "myWorkflow". The foo parameter is given the value bar in the workflow invocation.

$ curl \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 --data '{
      "_key":"contractorOnboarding",
      "foo":"bar"
  }' \
 "http://localhost:8080/openidm/workflow/processinstance?_action=create"

Managing Scanned Tasks Over REST

OpenIDM provides a task scanning mechanism that enables you to perform a batch scan for a specified date in OpenIDM data, on a scheduled interval, and then to execute a task when this date is reached. For more information about scanned tasks, see "Scanning Data to Trigger Tasks".

OpenIDM provides REST access to the task scanner, as listed in the following table.

URI HTTP Operation Description

/openidm/taskscanner

GET

Lists the all scanning tasks, past and present.

/openidm/taskscanner/id

GET

Lists details of the given task.

/openidm/taskscanner?action=execute&name=_name

POST

Triggers the specified task scan run.

/openidm/taskscanner/id?_action=cancel

POST

Cancels the specified task scan run.

Accessing Log Entries Over REST

You can interact with the audit logs over REST, as shown in the following table. Queries on the audit endpoint must use queryFilter syntax. Predefined queries (invoked with the _queryId parameter) are not supported.

URI HTTP Operation Description

/openidm/audit/recon?_queryFilter=true

GET

Displays the reconciliation audit log

/openidm/audit/recon/id

GET

Reads a specific reconciliation audit log entry

/openidm/audit/recon/id

PUT

Creates a reconciliation audit log entry

/openidm/audit/recon?queryFilter=/reconId+eq+"_reconId"

GET

Queries the audit log for a particular reconciliation operation

/openidm/audit/recon?queryFilter=/reconId+eq+"_reconId"and+situation+eq"situation"

GET

Queries the reconciliation audit log for a specific reconciliation situation

/openidm/audit/sync?_queryFilter=true

GET

Displays the synchronization audit log

/openidm/audit/sync/id

GET

Reads a specific synchronization audit log entry

/openidm/audit/sync/id

PUT

Creates a synchronization audit log entry

/openidm/audit/activity?_queryFilter=true

GET

Displays the activity log

/openidm/audit/activity/id

GET

Returns activity information for a specific action

/openidm/audit/activity/id

PUT

Creates an activity audit log entry

/openidm/audit/activity?queryFilter=transactionId=_id

GET

Queries the activity log for all actions resulting from a specific transaction

/openidm/audit/access?_queryFilter=true

GET

Displays the full list of auditable actions.

/openidm/audit/access/id

GET

Displays information on the specific audit item

/openidm/audit/access/id

PUT

Creates an access audit log entry

/openidm/audit/authentication?_queryFilter=true

GET

Displays a complete list of authentication attempts, successful and unsuccessful

/openidm/audit/authentication?_queryFilter=/principal+eq+"principal"

GET

Displays the authentication attempts by a specified user

/openidm/audit?_action=availableHandlers

POST

Returns a list of audit event handlers

/openidm/audit/config?_queryFilter=true

GET

Lists changes made to the configuration

Managing Reconciliation Operations Over REST

You can interact with the reconciliation engine over REST, as shown in the following table.

URI HTTP Operation Description

/openidm/recon

GET

Lists all completed reconciliation runs

/openidm/recon?_action=recon&mapping=mapping-name

POST

Launches a reconciliation run with the specified mapping

/openidm/recon/id?_action=cancel

POST

Cancels the specified reconciliation run

/openidm/system/datastore/account?_action=liveSync

POST

Calls a LiveSync operation.

The following example runs a reconciliation action, with the mapping systemHrdb_managedUser, defined in the sync.json file.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/recon?_action=recon&mapping=systemHrdb_managedUser"

Managing the Security Service Over REST

You can interact with the security service over REST, as shown in the following table:

URI

HTTP Operation

Description

/openidm/security/keystore

GET

Lists the keys and certificate in the keystore

/openidm/security/keystore/privatekey/alias

PUT

Imports a signed certificate into the keystore

/openidm/security/keystore?_action=generateCert

POST

Generates a self-signed certificate and imports it into the keystore

/openidm/security/keystore?_action=generateCSR

POST

Generates a certificate signing request, for submission to a certificate authority

/openidm/security/truststore

GET

Lists the public keys and certificate in the truststore

For sample REST commands, see "Accessing the Security Management Service".

Managing the Repository Over REST

You can interact with the repository engine over REST, as shown in the following table.

URI HTTP Operation Description

/openidm/repo/synchronisation/deadLetterQueue/resource?_queryId=query-all-ids

GET

Lists any failed synchronisation records for that resource, that have been placed in the dead letter queue.

/openidm/repo/link?_queryId=query-all-ids

GET

Lists entries in the links table

/openidm/repo/internal/user?_queryId=query-all-ids

GET

Lists the internal users

/openidm/repo/internal/user/username

PUT

Enables you to change the username or password of an internal user

/openidm/repo?_action=updateDbCredentials

POST

Enables you to change the database username and password, in the case of an OrientDB repository

For examples of queries on the repo/ endpoint, see "Interacting With the Repository Over REST".

Managing Updates Over REST

You can interact with the updates engine over REST, as shown in the following table.

URI HTTP Operation Description

/openidm/maintenance/update?_action=available

POST

Lists update archives in the project-dir/openidm/bin/update/ directory

/openidm/maintenance/update?_action=preview&archive=patch.zip

POST

Lists file states of the current installation, relative to the patch.zip archive, using checksums

openidm/maintenance/update?_action=listMigrations&archive=patch.zip

POST

Gets a list of repository migrations for a given update type

/openidm/maintenance/update?_action=getLicense&archive=patch.zip

POST

Retrieves the license from the patch.zip archive

/openidm/maintenance/update?_action=listRepoUpdates&archive=patch.zip

POST

Get a list of repository update archives; use the path in the output for the endpoint with repo files

/openidm/maintenance/update/archives/patch.zip/path?_field=contents&_mimeType=text/plain

POST

Get files for the specific repository update, defined in the path.

/openidm/maintenance?_action=enable

POST

Activates maintenance mode; you should first run the commands in "Pausing Scheduled Tasks".

/openidm/maintenance?_action=disable

POST

Disables maintenance mode; you can then re-enable scheduled tasks as noted in "Resuming All Running Scheduled Tasks".

/openidm/maintenance?_action=status

POST

Returns current maintenance mode information

/openidm/maintenance/update?_action=update&archive=patch.zip

POST

Start an update with the patch.zip archive

/openidm/maintenance/update?_action=installed

POST

Retrieve a summary of all installed updates

/openidm/maintenance/update?_action=restart

POST

Restart OpenIDM

/openidm/maintenance/update?_action=lastUpdateId

POST

Returns the _id value of the last successful update

/openidm/maintenance/update?_action=markComplete&updateId=id_string

POST

For an update with PENDING_REPO_UPDATES for one or more repositories, mark as complete. Replace id_string with the value of _id for the update archive.

/openidm/maintenance/update/log/_id

GET

Get information about an update, by _id (status, dates, file action taken)

/openidm/maintenance/update/log/?_queryFilter=true

GET

Get information about all past updates, by repository
Update Status Message
Status Description

IN_PROGRESS

Update has started, not yet complete

PENDING_REPO_UPDATES

OpenIDM update is complete, updates to the repository are pending

COMPLETE

Update is complete

FAILED

Update failed, not yet reverted

HTTP Status Codes

The OpenIDM REST API returns the standard HTTP response codes, as described in the following table.

HTTP Status Description

200 OK

The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.

201 Created

A request that created a new resource was completed. A representation of the new resource is returned. A Location header containing the canonical URI for the newly created resource should also be returned.

202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon. May happen with asynchronous communication.

204 No Content

The server fulfilled the request, but does not need to return a response message body.

400 Bad Request

The request could not be processed because it contains missing or invalid information.

401 Unauthorized

The authentication credentials included with this request are missing or invalid.

403 Forbidden

The server recognized your credentials, but you do not possess authorization to perform this request.

404 Not Found

The request specified a URI of a resource that does not exist.

405 Method Not Allowed

The HTTP verb specified in the request (DELETE, GET, POST, PUT) is not supported for this request URI.

406 Not Acceptable

The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.

409 Conflict

A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource).

412 Precondition Failed

The precondition given in the request header is false.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

501 Not Implemented

The server does not (currently) support the functionality required to fulfill the request.

503 Service Unavailable

The server is currently unable to handle the request due to temporary overloading or maintenance of the server.