<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-rest'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>REST API</title>

<sect1>

<title>REST API</title>

<sect2>

<title>Introduction</title>

<para/>

<para>Access to managed objects is provided through a REST API.</para>

<para/>

</sect2>

<sect2>

<title>URI scheme</title>

<para/>

<para>The URI scheme for accessing a managed object follows the convention, assuming the OpenIDM web application was deployed at /openidm: </para>

<para/>

<para>/openidm/managed/{type}/{id}</para>

<para/>

</sect2>

<sect2>

<title>Object identifier</title>

<para/>

<para>Each managed object has an identifier (expressed as {id} in the URI scheme), which is used to address it via the REST API. The REST API allows for the client-generated and server-generated identifiers, via PUT and POST methods. The default sever-generated identifier type is a UUID. Object identifiers that begin with underscore _ are reserved for future use. </para>

<para/>

</sect2>

<sect2>

<title>Content negotiation</title>

<para/>

<para>The REST API will fully support negotiation of content representation through the Accept HTTP header. While various media types will be supported in future releases, initially the content type supported is JSON; omitting content-negotiation will be equivalent to including the following header: </para>

<para/>

<para>Accept: application/json</para>

<para/>

</sect2>

<sect2>

<title>Conditional operations</title>

<para/>

<para>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.</para>

<para/>

</sect2>

<sect2>

<title>Supported methods</title>

<para/>

<para>The managed object API uses standard HTTP methods to access managed objects. </para>

<para/>

<sect3>

<title>GET</title>

<para/>

<para>Retrieves a managed object in OpenIDM. </para>

<para/>

<para>Request </para>

<programlisting language="http">

GET /openidm/managed/user/bdd793f8 HTTP/1.1

...</programlisting>

<para/>

<para>Response </para>

<example>

<programlisting language="http">

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 123

ETag: "7769ac1c6493"

…

[JSON representation of the managed object]</programlisting>

</example>

</sect3>

<sect3>

<title>HEAD</title>

<para/>

<para>Returns metainformation about a managed object in OpenIDM. </para>

<para/>

<para>Request </para>

<example>

<programlisting language="http">

HEAD /openidm/managed/user/bdd793f8 HTTP/1.1

…</programlisting>

</example>

<para/>

<para>Response </para>

<example>

<programlisting language="http">

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 123

ETag: "7769ac1c6493"</programlisting>

</example>

</sect3>

<sect3>

<title>PUT</title>

<para/>

<para>Creates or updates a managed object. PUT is the preferred method of creating managed objects. </para>

<para>Creating a new object</para>

<para/>

<para>Request </para>

<example>

<programlisting language="http">

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]</programlisting>

</example>

<para>Response </para>

<example>

<programlisting language="http">

HTTP/1.1 201 Created

Content-Type: application/json

Content-Length: 45

ETag: "238693bd8dae"

…

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

</programlisting>

</example>

<para>Updating an existing object</para>

<para/>

<para>Request</para>

<example>

<programlisting language="http">

PUT /openidm/managed/user/5752c0fd9509 HTTP/1.1

Content-Type: application/json

Content-Length: 123

If-Match: "238693bd8dae"

…

[JSON representation of managed object to update]</programlisting>

</example>

<para>Response (success)</para>

<example>

<programlisting language="http">

HTTP/1.1 204 No Content

ETag: "c3b7232fc0b3"

…</programlisting>

</example>

<para>Response (version conflict) </para>

<example>

<programlisting language="http">

HTTP/1.1 409 Conflict

Content-Type: application/json

Content-Length: 89

…

[JSON representation of error]</programlisting>

</example>

</sect3>

<sect3>

<title>POST</title>

<para/>

<para>The POST method allows arbitrary actions to be performed on managed objects. The _action query parameter defines the action to be performed.</para>

<para>Creating a new object</para>

<para/>

<para>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.</para>

<para/>

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

<para/>

<para>Request</para>

<example>

<programlisting language="http">

POST /openidm/managed/user?_action=create HTTP/1.1

Content-Type: application/json

Content-Length: 123

…

[JSON representation of the managed object to create]</programlisting>

</example>

<para>Response</para>

<example>

<programlisting language="http">

HTTP/1.1 201 Created

Content-Type: application/json

Content-Length: 45

ETag: "238693bd8dae"

…

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

</programlisting>

</example>

</sect3>

<sect3>

<title>DELETE</title>

<para/>

<para>Deletes a managed object.</para>

<para/>

<para>Request</para>

<example>

<programlisting language="http">

DELETE /openidm/managed/user/c3471805b60f

If-Match: "238693bd8dae"

…</programlisting>

</example>

<para>Response (success)</para>

<example>

<programlisting language="http">

HTTP/1.1 204 No Content

…</programlisting>

</example>

<para>Response (version conflict)</para>

<example>

<programlisting language="http">

HTTP/1.1 409 Conflict

Content-Type: application/json

Content-Length: 89

…

[JSON representation of error]</programlisting>

</example>

</sect3>

<sect3>

<title>PATCH</title>

<para/>

<para>Performs a partial modification of a managed object.</para>

<para/>

<para>Request</para>

<example>

<programlisting language="http">

PATCH /openidm/managed/user/5752c0fd9509 HTTP/1.1

Content-Type: application/patch+json

Content-Length: 456

If-Match: "238693bd8dae"

…

[JSON representation of patch document to apply]</programlisting>

</example>

<para>Response (success)</para>

<example>

<programlisting language="http">

HTTP/1.1 204 No Content

ETag: "c3b7232fc0b3"

…</programlisting>

</example>

<para>Response (version conflict)</para>

<example>

<programlisting language="http">

HTTP/1.1 409 Conflict

Content-Type: application/json

Content-Length: 89

…

[JSON representation of error]</programlisting>

</example>

<para>X-HTTP-Method-Override</para>

<para/>

<para>If an HTTP client or server container does not support a particular method, a request can be submitted via POST with the X-HTTP-Method-Override header set to the intended method.</para>

<para/>

<para>Request</para>

<example>

<programlisting language="http">

POST /openidm/managed/user/5752c0fd9509 HTTP/1.1

X-HTTP-Method-Override: PATCH

Content-Type: application/patch+json

Content-Length: 456

If-Match: "238693bd8dae"

…

[JSON representation of patch document to apply]</programlisting>

</example>

</sect3>

</sect2>

</sect1>

</chapter>