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. Synchronization Reference Scripting Reference