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
57d6342a74476c0bf2200992e778229d62ab1fa6mark ! Copyright 2013-2015 ForgeRock AS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
ec40cc0dc62425cea5d63fd9d984f8614479de25mark OpenDJ lets you access directory data as
ec40cc0dc62425cea5d63fd9d984f8614479de25mark <link xlink:show="new" xlink:href="http://json.org">JSON</link>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark resources over HTTP.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark This chapter demonstrates basic RESTful client operations
ec40cc0dc62425cea5d63fd9d984f8614479de25mark by using the default configuration
ec40cc0dc62425cea5d63fd9d984f8614479de25mark and sample directory data imported into OpenDJ from
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Before trying the examples, enable HTTP access to
08248b5c5b494aff8d1922e8e0b5777796d7450dmark OpenDJ directory server as described in procedure,
08248b5c5b494aff8d1922e8e0b5777796d7450dmark xlink:href="admin-guide#setup-rest2ldap-connection-handler"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark ><citetitle>To Set Up REST Access to OpenDJ Directory Server</citetitle></link>.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark The examples in this chapter use HTTP,
08248b5c5b494aff8d1922e8e0b5777796d7450dmark but the procedure also shows how to set up HTTPS access to the server.
57d6342a74476c0bf2200992e778229d62ab1fa6mark <para>Interface stability: <link xlink:href="reference#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>
11c8879df183d75f9c77c3d31a385d29dc530120mark This parameter is used though not shown in most examples that follow.
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>
11c8879df183d75f9c77c3d31a385d29dc530120mark$ <userinput>curl http://opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "code" : 401,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "reason" : "Unauthorized",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "message" : "Unauthorized"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>,
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "HTTP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set authentication-required:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdn: uid=bjensen,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuid: bjensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmark </programlisting>
05ea190b74e46ebd018e682afa477d4235344277mark Given this pattern in the user entries,
05ea190b74e46ebd018e682afa477d4235344277mark the default REST to LDAP configuration assumes that the user name
05ea190b74e46ebd018e682afa477d4235344277mark on the HTTP side is the value of the user ID,
05ea190b74e46ebd018e682afa477d4235344277mark and that user entries can be found directly under
05ea190b74e46ebd018e682afa477d4235344277mark <literal>ou=People,dc=example,dc=com</literal>.<footnote>
05ea190b74e46ebd018e682afa477d4235344277mark In general, REST to LDAP mappings require
05ea190b74e46ebd018e682afa477d4235344277mark that LDAP entries mapped to JSON resources
05ea190b74e46ebd018e682afa477d4235344277mark be immediate subordinates of the mapping's baseDN.
05ea190b74e46ebd018e682afa477d4235344277mark </footnote>
05ea190b74e46ebd018e682afa477d4235344277mark In other words, Babs Jensen authenticates as <literal>bjensen</literal>
05ea190b74e46ebd018e682afa477d4235344277mark This is mapped for an LDAP bind to the bind DN
05ea190b74e46ebd018e682afa477d4235344277mark <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With HTTP Basic authentication, it looks like this.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user bjensen:hifalutin \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Or, using the HTTP Basic
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the URL, it looks like this.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With HTTP header based authentication, it looks like this.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --header "X-OpenIDM-Username: bjensen" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --header "X-OpenIDM-Password: hifalutin" \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000016cbb68c",
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PUT \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --header "If-None-Match: *" \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "newuser",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "contactInformation": {
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "telephoneNumber": "+1 408 555 1212",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "emailAddress": "newuser@example.com"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "familyName": "New",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "givenName": "User"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "New User",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "manager": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "kvaughan",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Kirsten Vaughan"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/newuser</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request GET \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/newuser</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PUT \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "contactInformation": {
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "telephoneNumber": "+1 408 555 4798",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "emailAddress": "scarter@example.com"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "familyName": "Carter",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "givenName": "Sam"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "userName": "scarter@example.com",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Sam Carter",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "groups": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "Accounting Managers"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "manager": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "trigden",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Torrey Rigden"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/scarter</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark http://opendj.example.com:8080/users/scarter?_fields=_rev</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{"_rev":"00000000b017c5b8"}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PUT \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark--header "If-Match: 00000000b017c5b8" \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "contactInformation": {
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "telephoneNumber": "+1 408 555 1212",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "emailAddress": "scarter@example.com"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "familyName": "Carter",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "givenName": "Sam"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "userName": "scarter@example.com",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Sam Carter",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "groups": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "Accounting Managers"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "manager": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "trigden",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Torrey Rigden"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/scarter</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request DELETE \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/newuser</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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 --user kvaughan:bribery
08248b5c5b494aff8d1922e8e0b5777796d7450dmark http://opendj.example.com:8080/users/newuser?_fields=_rev</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{"_rev":"000000006d8d7358"}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request DELETE \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --header "If-Match: 000000006d8d7358" \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/newuser</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&)" dn</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=nbohr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "HTTP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "HTTP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Delete as a user who has rights to perform a subtree delete on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the resource.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request DELETE \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PATCH \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "operation": "replace",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "value": "babs@example.com"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
57d6342a74476c0bf2200992e778229d62ab1fa6mark If the target field is single-valued and a value already exists,
57d6342a74476c0bf2200992e778229d62ab1fa6mark then that value is replaced with the value you provide.
57d6342a74476c0bf2200992e778229d62ab1fa6mark <emphasis>Note that you do not get an error when adding a value
57d6342a74476c0bf2200992e778229d62ab1fa6mark to a single-valued field that already has a value.</emphasis>
57d6342a74476c0bf2200992e778229d62ab1fa6mark A single-valued field is one whose value is not an array
57d6342a74476c0bf2200992e778229d62ab1fa6mark (an object, string, boolean, or number).
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PATCH \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "operation": "add",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "field": "/members",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "value": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "bjensen"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/groups/Directory%20Administrators</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PATCH \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "operation": "remove",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "field": "/members",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "value": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "bjensen"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/groups/Directory%20Administrators</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/bjensen?_fields=_rev</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000c1b6d4c7"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request PATCH \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --header "If-Match: 00000000c1b6d4c7" \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "operation": "add",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "value": "babs@example.com"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --request POST \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "newuser",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "contactInformation": {
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "telephoneNumber": "+1 408 555 1212",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "emailAddress": "newuser@example.com"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "familyName": "New",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "givenName": "User"
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "New User",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "manager": [
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "_id": "kvaughan",
e6130d384f5f6ef1c13178e112a021c208c4db0dmark "displayName": "Kirsten Vaughan"
11c8879df183d75f9c77c3d31a385d29dc530120mark http://opendj.example.com:8080/users?_action=create</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To query resource collections, perform an HTTP GET with a
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark <literal>_queryFilter=<replaceable>expression</replaceable></literal> parameter
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in your query string.</para>
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark The following listing summarizes the string representation
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark for the filter expression.
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark Continue reading for additional explanation.
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkExpr = OrExpr
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkOrExpr = AndExpr ( 'or' AndExpr ) *
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkAndExpr = NotExpr ( 'and' NotExpr ) *
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkNotExpr = '!' PrimaryExpr | PrimaryExpr
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkPrimaryExpr = '(' Expr ')' | ComparisonExpr | PresenceExpr | LiteralExpr
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkComparisonExpr = Pointer OpName JsonValue
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkPresenceExpr = Pointer 'pr'
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkLiteralExpr = 'true' | 'false'
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkPointer = JSON pointer
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkOpName = 'eq' | # equal to
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'co' | # contains
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'sw' | # starts with
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'lt' | # less than
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'le' | # less than or equal to
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'gt' | # greater than
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark 'ge' | # greater than or equal to
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark STRING # extended operator
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkJsonValue = NUMBER | BOOLEAN | '"' UTF8STRING '"'
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkSTRING = ASCII string not containing white-space
f80939e0a6cb3b086f27d003d204d792f55f4f0bmarkUTF8STRING = UTF-8 string possibly containing white-space
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark </programlisting>
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark The following table shows some LDAP search filters
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark with corresponding query filter expressions.
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark LDAP Filter
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark REST Filter
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=true
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+pr
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (uid=bjensen)
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+eq+"bjensen"
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (uid=*jensen*)
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+co+"jensen"
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (uid=jensen*)
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+sw+"jensen"
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (&(uid=*jensen*)(cn=babs*))
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=(_id+co+"jensen"+and+displayName+sw+"babs")
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (|(uid=*jensen*)(cn=sam*))
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=(_id+co+"jensen"+or+displayName+sw+"sam")
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (!(uid=*jensen*))
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=!(_id+co+"jensen")
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (uid<=jensen)
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+le+"jensen"
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark (uid>=jensen)
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark _queryFilter=_id+ge+"jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark <para>For query operations, your filter <replaceable>expression</replaceable>
f80939e0a6cb3b086f27d003d204d792f55f4f0bmark is 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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+eq+"bjensen@example.com"'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+co+"jensen"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+sw+"ab"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abergin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+lt+"ac"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abarnes@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "abergin@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+le+"ad"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+gt+"tt"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName+ge+"tw"&_fields=userName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "tward@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "wlutz@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/users?_queryFilter=userName%20pr'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'http://opendj.example.com:8080/groups?_queryFilter=true&_fields=displayName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user kvaughan:bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark(userName+co+"jensen"+and+manager/displayName+sw+"Sam")&_fields=displayName'</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "result" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Jody Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Ted Jensen"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "resultCount" : 2,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "pagedResultsCookie" : null,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
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 <variablelist>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark You can page through search results using the following query string parameters.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
cecccb994480c14e2c687f83e31bf595f73d671dmark <term><literal>_pagedResultsCookie=<replaceable>string</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
cecccb994480c14e2c687f83e31bf595f73d671dmark Opaque cookie used by the server to keep track of the position
cecccb994480c14e2c687f83e31bf595f73d671dmark in the search results.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark In the request also set <literal>_pageSize</literal> greater than zero.
cecccb994480c14e2c687f83e31bf595f73d671dmark You receive the cookie value from the server on the first request,
cecccb994480c14e2c687f83e31bf595f73d671dmark and then supply the cookie value in subsequent requests
cecccb994480c14e2c687f83e31bf595f73d671dmark until the server returns a <literal>null</literal> cookie,
cecccb994480c14e2c687f83e31bf595f73d671dmark meaning that the final page of results has been returned.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
cecccb994480c14e2c687f83e31bf595f73d671dmark <term><literal>_pagedResultsOffset=<replaceable>integer</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark When <literal>_pageSize</literal> is greater than zero,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark use this as an index in the result set indicating the page to return.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark When the value of <literal>_pagedResultsOffset</literal> is 1 or more,
cecccb994480c14e2c687f83e31bf595f73d671dmark the server returns the page starting from the specified index.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark When <literal>_pagedResultsCookie</literal> is also set,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark the starting point is the position tracked by the cookie.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark Otherwise the offset is relative to the beginning of the result set.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark For example, <literal>_pageSize=2&_pagedResultsOffset=1</literal>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark returns the third and fourth entries of the results.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark <literal>_pageSize=3&_pagedResultsOffset=2&_pagedResultsCookie=<replaceable>cookie</replaceable></literal>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark returns the seventh, eighth, and ninth entries
34e005797ceeb73a42252a45a2f3b3f6a102552cmark counting from the position tracked by the cookie.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark or when the value of <literal>_pagedResultsOffset</literal> is 0 or less,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark the setting has no effect.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark but the offset points to a page beyond the last of the search results,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark the result set returned is empty.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
cecccb994480c14e2c687f83e31bf595f73d671dmark <term><literal>_pageSize=<replaceable>integer</replaceable></literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark Return query results in pages of this size,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark where <replaceable>integer</replaceable> should be greater than zero.
34e005797ceeb73a42252a45a2f3b3f6a102552cmark Page sizes of zero or less have no effect,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark with the outcome that all results are returned,
34e005797ceeb73a42252a45a2f3b3f6a102552cmark and <literal>_pagedResultsCookie</literal> is <literal>null</literal>
34e005797ceeb73a42252a45a2f3b3f6a102552cmark in the response.
cecccb994480c14e2c687f83e31bf595f73d671dmark After the initial request, use <literal>_pagedResultsCookie</literal>
cecccb994480c14e2c687f83e31bf595f73d671dmark to page through the results.
cecccb994480c14e2c687f83e31bf595f73d671dmark The following example demonstrates the use of paged results.
cecccb994480c14e2c687f83e31bf595f73d671dmark The first call requests 5 results per page, and retrieves the first page.
cecccb994480c14e2c687f83e31bf595f73d671dmark The next call provides the cookie to request the next 5 results.
cecccb994480c14e2c687f83e31bf595f73d671dmark The final call provides the cookie and requests the 10th page of results
34e005797ceeb73a42252a45a2f3b3f6a102552cmark after the last page of results specified by the cookie.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user bjensen:hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
cecccb994480c14e2c687f83e31bf595f73d671dmark "result" : [ {
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "abarnes@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "abergin@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "achassin@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "ahall@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "ahel@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "resultCount" : 5,
cecccb994480c14e2c687f83e31bf595f73d671dmark "pagedResultsCookie" : "AAAAAAAAAA8=",
cecccb994480c14e2c687f83e31bf595f73d671dmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user bjensen:hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5\
08248b5c5b494aff8d1922e8e0b5777796d7450dmark&_pagedResultsCookie=AAAAAAAAAA8="</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
cecccb994480c14e2c687f83e31bf595f73d671dmark "result" : [ {
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "ahunter@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "ajensen@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "aknutson@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "alangdon@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "alutz@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "resultCount" : 5,
cecccb994480c14e2c687f83e31bf595f73d671dmark "pagedResultsCookie" : "AAAAAAAAABQ=",
cecccb994480c14e2c687f83e31bf595f73d671dmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user bjensen:hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5\
08248b5c5b494aff8d1922e8e0b5777796d7450dmark&_pagedResultsCookie=AAAAAAAAAA8=&_pagedResultsOffset=10"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
cecccb994480c14e2c687f83e31bf595f73d671dmark "result" : [ {
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "gtriplet@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "gtyler@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "hmiller@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "jbourke@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "userName" : "jbrown@example.com"
cecccb994480c14e2c687f83e31bf595f73d671dmark "resultCount" : 5,
cecccb994480c14e2c687f83e31bf595f73d671dmark "pagedResultsCookie" : "AAAAAAAAAEY=",
cecccb994480c14e2c687f83e31bf595f73d671dmark "remainingPagedResults" : -1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
cecccb994480c14e2c687f83e31bf595f73d671dmark Notice that <literal>"remainingPagedResults" : -1</literal> in each case
cecccb994480c14e2c687f83e31bf595f73d671dmark meaning that the number of remaining results is not known.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>