chap-rest-operations.xml revision 51607ea01068c9047391e4c8b46bc9dbd0edb7fd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Copyright 2013 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ lets you access directory data as JSON resources over HTTP.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark This chapter demonstrates basic RESTful client operations using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default configuration and sample directory data imported into OpenDJ from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >Example.ldif</link>. Before trying the examples, enable HTTP access to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ directory server as described in procedure, <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#setup-rest2ldap-connection-handler"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Access to OpenDJ Directory Server</citetitle></link>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The OpenDJ REST API is built on a common ForgeRock HTTP-based REST API
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for interacting with JSON Resources. APIs built on this common layer all let
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you perform the following operations.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The present implementation in OpenDJ maps JSON resources onto LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entries, meaning REST clients can in principle do just about anything an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark LDAP client can do with directory data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In addition to query string parameters that depend on the operation,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the examples in this chapter make use of the following parameters that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark apply to the JSON resource returned for all operations.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>_fields=<replaceable>field</replaceable>[,…]</literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Retain only the specified fields in the JSON resource returned.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>_prettyPrint=true|false</literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make the JSON resource returned easy for humans to read.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you first try to get a resource that you can read as an LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry with an anonymous search, you might be surprised that you must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authenticate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "code" : 401,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "reason" : "Unauthorized",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "message" : "Unauthorized"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>HTTP status code 401 tells your HTTP client that the request requires
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark user authentication. You can change this behavior by setting the HTTP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection handler property, <literal>authentication-required</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-connection-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name "HTTP Connection Handler"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set authentication-required:false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Out of the box both the HTTP Connection Handler and also the REST LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark gateway are configured to allow HTTP Basic authentication and HTTP header
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark based authentication in the style of OpenIDM. The authentication mechanisms
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark translate HTTP authentication to LDAP authentication on the directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark side.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you install OpenDJ either with generated sample user entries or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with data from <link xlink:href="http://opendj.forgerock.org/Example.ldif"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:show="new">Example.ldif</link>, the relative distinguished name
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute for the sample user entries is the user ID (<literal>uid</literal>)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute. For example, the DN and user ID for Babs Jensen are as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark follows.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: bjensen</programlisting>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Given this pattern in the user entries, the default REST to LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration assumes that the user name on the HTTP side is the value of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the user ID, and that user entries can be found under
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal>. In other words, Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>hifalutin</literal>) over HTTP. This is mapped for an LDAP bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the bind DN <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With HTTP Basic authentication, it looks like this.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user bjensen:hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Or, using the HTTP Basic
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the URL, it looks like this.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhttp://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With HTTP header based authentication, it looks like this.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --header "X-OpenIDM-Username: bjensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --header "X-OpenIDM-Password: hifalutin"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If your directory data are laid out differently, or if your user names
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark are email addresses rather than user IDs for example, then you must update
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the configuration in order for authentication to work.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The REST LDAP gateway can also translate HTTP user name and password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication to PLAIN SASL authentication on the LDAP side. Moreover, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark gateway can fall back to proxied authorization as necessary, using a root DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authenticated connection to LDAP servers. See <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Configuration</citetitle></link> for details on all configuration
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark choices.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To create a resource using an ID that you specify, perform an HTTP PUT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark request with headers <literal>Content-Type: application/json</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>If-None-Match: *</literal>, and the JSON content of your
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark resource.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example creates a new user entry with ID
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PUT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --header "If-None-Match: *"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation": {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber": "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress": "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName": "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName": "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/newuser?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "000000005b337348",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-04-11T09:58:27Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To create a resource letting the server choose the ID, perform an HTTP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark POST with <literal>_action=create</literal> as described in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request GET
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/newuser?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "000000005b337348",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-04-11T09:58:27Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To update a resource, perform an HTTP PUT with the changes to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark resource. For read-only fields, either include unmodified versions, or omit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark them from your updated version.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example adds a manager for Sam Carter.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PUT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation": {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber": "+1 408 555 4798",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress": "scarter@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName": "Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName": "Sam"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName": "scarter@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Sam Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "groups": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "Accounting Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/scarter?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000a1923db2",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 4798",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "scarter@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "scarter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Sam"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "scarter@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Sam Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-04-12T07:42:34Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "groups" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "Accounting Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To update a resource only if the resource matches a particular version,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark use an <literal>If-Match: <replaceable>revision</replaceable></literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark header.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen> $ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/scarter?_fields=_rev
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PUT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <emphasis>--header "If-Match: 00000000b017c5b8"</emphasis>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation": {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber": "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress": "scarter@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName": "Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName": "Sam"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName": "scarter@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Sam Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "groups": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "Accounting Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/scarter?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000a1ee3da3",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "scarter@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "scarter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Sam"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "scarter@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Sam Carter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-04-12T07:47:45Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "groups" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "Accounting Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To delete a resource, perform an HTTP DELETE on the resource URL.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark On success, the operation returns the resource you deleted.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request DELETE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/newuser?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "000000003a5f3cb2",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-04-11T09:58:27Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To delete a resource only if the resource matches a particular version,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark use an <literal>If-Match: <replaceable>revision</replaceable></literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark header.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/newuser?_fields=_rev
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark{"_rev":"000000006d8d7358"}
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request DELETE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --header "If-Match: 000000006d8d7358"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/newuser?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000383f3cae",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-04-11T12:48:48Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To delete a resource and all its children, you must change the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration, get the REST LDAP gateway or HTTP Connection Handler to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reload its configuration, and perform the operation as a user who has the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark access rights required. The following steps show one way to do this with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the HTTP Connection Handler.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this case the LDAP view of the user to delete shows two child
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entries.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&)" dn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=nbohr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In the configuration file for the HTTP Connection Handler, by default
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>/path/to/opendj/config/http-config.json</filename>, set
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>After this change, only users who have access to request a tree
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark delete can delete resources.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Force the HTTP Connection Handler to reread its configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-connection-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name "HTTP Connection Handler"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-connection-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name "HTTP Connection Handler"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Delete as a user who has rights to perform a subtree delete on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the resource.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request DELETE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/nbohr?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "000000003d912113",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "nbohr@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "nbohr",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Bohr",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Niels"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "nbohr@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Niels Bohr"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ lets you patch JSON resources, updating part of the resource
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rather than replacing it. For example, you could change Babs Jensen's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark email address by issuing an HTTP PATCH request, as in the example that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark follows.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Notice that the data sent specifies the type of patch operation, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark field to change, and a value that depends on the field you change and on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark operation. A single-valued field takes an object, boolean, string, or number
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark depending on its type, whereas a multi-valued field takes an array of values.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Getting the type wrong results in an error. Also notice that the patch data is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark itself an array, since you could patch more than one part of the resource by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark using a set of patch operations in the same request.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PATCH
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "operation": "replace",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "value": "babs@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000f3fdd370",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1862",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "babs@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Barbara"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "babs@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-05-13T14:35:31Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ supports four types of patch operation.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The add operation ensures that the target field contains the value
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provided, creating parent fields as necessary.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the target field is single-valued and a value already exists, then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that value is replaced with the value you provide. <emphasis
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark role="strong">Note that you do not get an error when adding a value to a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark single-valued field that already has a value.</emphasis> A single-valued
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark field is one whose value is not an array (an object, string, boolean, or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark number).</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the target field is multi-valued, then the array of values you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provide is merged with the set of values already in the resource. New
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark values are added, and duplicate values are ignored. A multi-valued field
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark takes an array value.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The remove operation ensures that the target field does not contain
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the value provided. If you do not provide a value, the entire field is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark removed if it already exists.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the target field is single-valued and a value is provided, then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the provided value must match the existing value to remove, otherwise the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark field is left unchanged.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the target field is multi-valued, then values in the array you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provide are removed from the existing set of values.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The replace operation removes existing values on the target field,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and replaces them with the values you provide. It is equivalent to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark performing a remove on the field, then an add with the values you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provide.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The increment operation increments or decrements the value or values
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the target field by the amount you specify, which is positive to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark increment, negative to decrement. The target field must be a number or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a set of numbers. The value you provide must be a single number.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>One key nuance in how patch works with OpenDJ has to do with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark multi-valued fields. Although JSON resources represent multi-valued fields as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <emphasis>arrays</emphasis>, OpenDJ treats those values as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <emphasis>sets</emphasis>. In other words, values in the field are unique,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and the ordering of an array of values is not meaningful in the context of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark patch operations. If you reference array values by index, OpenDJ returns
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an error.<footnote><para>OpenDJ does let you use a hyphen as the last element
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of the "field" JSON pointer value to add an element to the set, as in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>curl --user kvaughan:bribery --request PATCH --header "Content-Type:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application/json" --data '[{ "operation" : "add", "field" : "/members/-",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "value" : { "_id" : "bjensen" } }]'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/groups/Directory%20Administrators</command>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Instead use the patch operations as if arrays values were sets. For
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example, you can include Barbara Jensen in a group by adding her to the set
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of members.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PATCH
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "operation": "add",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "field": "/members",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "value": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "bjensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/groups/Directory%20Administrators
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000b70c881a",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "Directory Administrators",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Directory Administrators",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-05-13T16:40:23Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "members" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "rdaugherty",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Robert Daugherty"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "hmiller",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Harry Miller"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PATCH
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "operation": "remove",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "field": "/members",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "value": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "bjensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/groups/Directory%20Administrators
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000e241797e",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "Directory Administrators",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Directory Administrators",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-05-13T16:40:55Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "members" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "rdaugherty",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Robert Daugherty"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "hmiller",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Harry Miller"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can use resource revision numbers in <literal>If-Match:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>revision</replaceable></literal> headers to patch the resource
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark only if the resource matches a particular version.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "http://opendj.example.com:8080/users/bjensen?_prettyPrint=true&_fields=_rev"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000c1b6d4c7"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request PATCH
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --header "If-Match: 00000000c1b6d4c7"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "operation": "add",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "value": "babs@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000f946d377",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1862",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "babs@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Barbara"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "babs@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "lastModified" : "2013-05-13T16:56:33Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The resource revision changes after you successfully perform the patch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark operation.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ implements an action that lets the server set the resource ID
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark on creation. To use this action, perform an HTTP POST with header
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>_action=create</literal> in the query string, and the JSON content of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark your resource.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example creates a new user entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --request POST
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --user kvaughan:bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation": {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber": "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress": "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName": "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName": "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager": [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id": "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName": "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "http://opendj.example.com:8080/users?_action=create&_prettyPrint=true"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000034a23ca7",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1212",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "newuser@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-04-11T11:19:08Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "kvaughan",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Kirsten Vaughan"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To query resource collections, perform an HTTP GET with a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>_queryFilter=<replaceable>filter</replaceable></literal> parameter
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in your query string.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For query operations, your <replaceable>filter</replaceable>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark expressions are constructed from the following building blocks.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Make sure you URL encode the filter expressions, which are shown here
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark without URL encoding to make them easier to read.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In these expressions the simplest
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>json-pointer</replaceable> is a field of the JSON resource,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark such as <literal>userName</literal> or <literal>id</literal>. A
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>json-pointer</replaceable> can however point to nested
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer">JSON
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can build filters using the following comparison expressions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> eq <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer equals the value, as in the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+eq+"bjensen@example.com"&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000315fb731",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1862",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "bjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Barbara"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "bjensen@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 1,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> co <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer contains the value, as in the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+co+"jensen"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "ajensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "bjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "gjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "jjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "kjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "rjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "tjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 7,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> sw <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer starts with the value, as in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+sw+"ab"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abergin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> lt <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer is less than the value, as in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+lt+"ac"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abergin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> le <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer is less than or equal to the value, as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+le+"ad"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abergin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "achassin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 3,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> gt <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer is greater than the value, as in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+gt+"tt"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "ttully@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "tward@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "wlutz@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 3,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal><replaceable>json-pointer</replaceable> ge <replaceable>json-value</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Matches when the pointer is greater than or equal to the value,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as in the following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName+ge+"tw"&_fields=userName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "tward@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "wlutz@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><literal><replaceable>json-pointer</replaceable> pr</literal> matches
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark any resource on which the <replaceable>json-pointer</replaceable> is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark present, as in the following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=userName%20pr&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "000000002210a544",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "scarter",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Sam Carter"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 9445",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "abarnes",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Barnes",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Anne-Louise"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Anne-Louise Barnes"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark },… many entries omitted …
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "newuser",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "New",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "User"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "newuser@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "New User",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "meta" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "created" : "2013-03-26T10:52:42Z"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 152,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><literal>true</literal> matches any resource in the collection.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><literal>false</literal> matches no resource in the collection.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In other words you can list all resources in a collection as in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /groups?_queryFilter=true&_fields=displayName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Accounting Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Directory Administrators"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "HR Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "PD Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "QA Managers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 5,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can combine expressions using boolean operators
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>and</literal>, <literal>or</literal>, and <literal>!</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (not), using parentheses,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>(<replaceable>expression</replaceable>)</literal>, to group
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark expressions. The following example queries resources with last name
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Jensen and manager name starting with <literal>Bar</literal>. Notice that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the filters use the JSON pointers <literal>name/familyName</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>manager/displayName</literal> to identify the fields that are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark nested inside the <literal>name</literal> and <literal>manager</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark objects.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /users?_queryFilter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark &_fields=displayName&_prettyPrint=true'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Jody Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Ted Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <!-- Pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-702
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can have the server sort JSON resources before it returns them by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark using the <literal>_sortKeys[+-]=<replaceable>field</replaceable>[,…]</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark query string.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <!-- Pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-701
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can page through search results using the following query string
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark parameters.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>__pagedResultsOffset=<replaceable>string</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>