REST API Structure

URI Scheme

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

/openidm/managed/type/id

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 directory might be:

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

Important

For LDAP resources, you should not map the LDAP dn to the Identity Cloud uidAttribute (_id). The attribute that is used for the _id should be immutable. You should therefore map the LDAP entryUUID operational attribute to the Identity Cloud _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.

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.

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 Identity Cloud's optimistic concurrency control system. Clients should make requests conditional in order to prevent inadvertent modification of the wrong version of an object. For managed objects, if no conditional header is specified, a default of If-Match: * is applied.

REST API Conditional Operations
HTTP HeaderOperationDescription
If-Match: <rev>PUTUpdate the object if the <rev> matches the revision level of the object.
If-Match: *PUTUpdate the object regardless of revision level
If-None-Match: <rev> Bad request
If-None-Match: *PUTCreate; fails if the object already exists
When the conditional operations If-Match, If-None-Match are not usedPUTUpsert; attempts a create, and then an update; if both attempts fail, return an error

Read a different version of :