OpenIDM Integrator's Guide
REST API Reference

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]