OpenIDM provides a RESTful API for accessing managed objects.
The URI scheme for accessing a managed object follows this
convention, assuming the OpenIDM web application was deployed at
/openidm.
/openidm/managed/type/id
Each managed object has an identifier (expressed as
id in the URI scheme) which is used to
address the object through the REST API. The REST API allows for the
client-generated and server-generated identifiers, through PUT and POST
methods. The default server-generated identifier type is a UUID. Object
identifiers that begin with underscore ( _ ) are reserved
for future use.
The REST API fully supports negotiation of content representation
through the Accept HTTP header. Currently, the supported
content type is JSON; omitting content-negotiation is equivalent to including
the following header:
Accept: application/json
The REST API fully 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.
The managed object API uses standard HTTP methods to access managed objects.
Retrieves a managed object in OpenIDM.
Example Request
GET /openidm/managed/user/bdd793f8 HTTP/1.1 ...
Example Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 123 ETag: "0" ... [JSON representation of the managed object]
Returns metainformation about a managed object in OpenIDM.
Example Request
HEAD /openidm/managed/user/bdd793f8 HTTP/1.1 ...
Example Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 123 ETag: "0"
Creates or updates a managed object. PUT is the preferred method of creating managed objects.
Example Request: Creating a new object
PUT /openidm/managed/user/5752c0fd9509 HTTP/1.1 Content-Type: application/json Content-Length: 123 If-None-Match: * ... [JSON representation of the managed object to create]
Example Response: Creating a new object
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 45 ETag: "0" ... [JSON representation containing metadata (underscore-prefixed) properties]
Example Request: Updating an existing object
PUT /openidm/managed/user/5752c0fd9509 HTTP/1.1 Content-Type: application/json Content-Length: 123 If-Match: "0" ... [JSON representation of managed object to update]
Example Response: Updating an existing object (success)
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 45 ETag: "0" ....
This return code may change in a future release.
Example Response: Updating an existing object when no version is supplied (version conflict)
HTTP/1.1 409 Conflict Content-Type: application/json 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 Content-Length: 89 ... [JSON representation of error]
The POST method allows arbitrary actions to be performed 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 is used to update one or more
attributes of a managed object, without replacing the entire object.
Example Create Request
POST /openidm/managed/user?_action=create HTTP/1.1 Content-Type: application/json Content-Length: 123 ... [JSON representation of the managed object to create]
Example Response
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 45 ETag: "0" ... [JSON representation containing metadata (underscore-prefixed) properties]
Example Patch Request
POST /openidm/managed/user?_action=patch HTTP/1.1 Content-Type: application/json Content-Length: 123 ... [JSON representation of the managed object to create]
Example Response (success)
HTTP/1.1 204 No Content ETag: "1" ...
Deletes a managed object.
Example Request
DELETE /openidm/managed/user/c3471805b60f If-Match: "0" ...
Example Response (success)
HTTP/1.1 204 No Content ...
Deleting an existing object when no version is supplied (version conflict)
HTTP/1.1 409 Conflict Content-Type: application/json Content-Length: 89 ... [JSON representation of error]
Example Response: Deleting an existing object when an invalid version is supplied (version conflict)
HTTP/1.1 412 Precondition Required Content-Type: application/json Content-Length: 89 ... [JSON representation of error]
Performs a partial modification of a managed object.
See the JSON Patch Internet-Draft for details.
Example Request
PATCH /openidm/managed/user/5752c0fd9509 HTTP/1.1 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 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 Content-Length: 89 ... [JSON representation of error]