HTTP JSON REST OpenDJ lets you access directory data as JSON resources over HTTP. This chapter demonstrates basic RESTful client operations using the default configuration and sample directory data imported into OpenDJ from Example.ldif. Before trying the examples, enable HTTP access to OpenDJ directory server as described in procedure, To Set Up REST Access to OpenDJ Directory Server. The examples in this chapter use HTTP, but the procedure also shows how to set up HTTPS access to the server. Interface stability: Evolving

The OpenDJ REST API is built on a common ForgeRock HTTP-based REST API for interacting with JSON Resources. APIs built on this common layer all let you perform the following operations. Create Add a resource that does not yet exist Read Retrieve a single resource Update Replace an existing resource Delete Remove an existing resource Patch Modify part of an existing resource Action Perform a predefined action Query List a set of resources The present implementation in OpenDJ maps JSON resources onto LDAP entries, meaning REST clients can in principle do just about anything an LDAP client can do with directory data. In addition to query string parameters that depend on the operation, the examples in this chapter make use of the following parameters that apply to the JSON resource returned for all operations. _fields=field[,…] Retain only the specified fields in the JSON resource returned. _prettyPrint=true|false Make the JSON resource returned easy for humans to read.

When you first try to get a resource that you can read as an LDAP entry with an anonymous search, you might be surprised that you must authenticate. $ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true { "code" : 401, "reason" : "Unauthorized", "message" : "Unauthorized" } HTTP status code 401 tells your HTTP client that the request requires user authentication. You can change this behavior by setting the HTTP connection handler property, authentication-required, to false. $ dsconfig \ set-connection-handler-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "HTTP Connection Handler" \ --set authentication-required:false \ --no-prompt \ --trustAll Out of the box both the HTTP Connection Handler and also the REST LDAP gateway are configured to allow HTTP Basic authentication and HTTP header based authentication in the style of OpenIDM. The authentication mechanisms translate HTTP authentication to LDAP authentication on the directory server side. When you install OpenDJ either with generated sample user entries or with data from Example.ldif, the relative distinguished name attribute for the sample user entries is the user ID (uid) attribute. For example, the DN and user ID for Babs Jensen are as follows. dn: uid=bjensen,ou=People,dc=example,dc=com uid: bjensen Given this pattern in the user entries, the default REST to LDAP configuration assumes that the user name on the HTTP side is the value of the user ID, and that user entries can be found under ou=People,dc=example,dc=com. In other words, Babs Jensen authenticates as bjensen (password: hifalutin) over HTTP. This is mapped for an LDAP bind to the bind DN uid=bjensen,ou=People,dc=example,dc=com. With HTTP Basic authentication, it looks like this. $ curl \ --user bjensen:hifalutin \ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true { "_rev" : "0000000016cbb68c", ... } Or, using the HTTP Basic username:password@ form in the URL, it looks like this. $ curl \ http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true { "_rev" : "0000000016cbb68c", ... } With HTTP header based authentication, it looks like this. $ curl \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: hifalutin" \ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true { "_rev" : "0000000016cbb68c", ... } If your directory data are laid out differently, or if your user names are email addresses rather than user IDs for example, then you must update the configuration in order for authentication to work. The REST LDAP gateway can also translate HTTP user name and password authentication to PLAIN SASL authentication on the LDAP side. Moreover, the gateway can fall back to proxied authorization as necessary, using a root DN authenticated connection to LDAP servers. See REST LDAP Configuration for details on all configuration choices.

There are two ways to create resources. To create a resource using an ID that you specify, perform an HTTP PUT request with headers Content-Type: application/json and If-None-Match: *, and the JSON content of your resource. The following example creates a new user entry with ID newuser. $ curl \ --request PUT \ --user kvaughan:bribery \ --header "Content-Type: application/json" \ --header "If-None-Match: *" \ --data '{ \ "_id": "newuser", \ "contactInformation": { \ "telephoneNumber": "+1 408 555 1212", \ "emailAddress": "newuser@example.com" \ }, \ "name": { \ "familyName": "New", \ "givenName": "User" \ }, \ "displayName": "New User", \ "manager": [ \ { \ "_id": "kvaughan", \ "displayName": "Kirsten Vaughan" \ } \ ] \ }' \ http://opendj.example.com:8080/users/newuser?_prettyPrint=true { "_rev" : "000000005b337348", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-04-11T09:58:27Z" }, "manager" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" } ] } To create a resource letting the server choose the ID, perform an HTTP POST with _action=create as described in .

To read a resource, perform an HTTP GET. $ curl \ --request GET \ --user kvaughan:bribery \ http://opendj.example.com:8080/users/newuser?_prettyPrint=true { "_rev" : "000000005b337348", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-04-11T09:58:27Z" }, "manager" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" } ] }

To update a resource, perform an HTTP PUT with the changes to the resource. For read-only fields, either include unmodified versions, or omit them from your updated version. The following example adds a manager for Sam Carter. $ curl \ --request PUT \ --user kvaughan:bribery \ --header "Content-Type: application/json" \ --data '{ \ "contactInformation": { \ "telephoneNumber": "+1 408 555 4798", \ "emailAddress": "scarter@example.com" \ }, \ "name": { \ "familyName": "Carter", \ "givenName": "Sam" \ }, \ "userName": "scarter@example.com", \ "displayName": "Sam Carter", \ "groups": [ \ { \ "_id": "Accounting Managers" \ } \ ], \ "manager": [ \ { \ "_id": "trigden", \ "displayName": "Torrey Rigden" \ } \ ] \ }' \ http://opendj.example.com:8080/users/scarter?_prettyPrint=true { "_rev" : "00000000a1923db2", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 4798", "emailAddress" : "scarter@example.com" }, "_id" : "scarter", "name" : { "familyName" : "Carter", "givenName" : "Sam" }, "userName" : "scarter@example.com", "displayName" : "Sam Carter", "manager" : [ { "_id" : "trigden", "displayName" : "Torrey Rigden" } ], "meta" : { "lastModified" : "2013-04-12T07:42:34Z" }, "groups" : [ { "_id" : "Accounting Managers" } ] } To update a resource only if the resource matches a particular version, use an If-Match: revision header. $ curl \ --user kvaughan:bribery \ http://opendj.example.com:8080/users/scarter?_fields=_rev {"_rev":"00000000b017c5b8"} $ curl \ --request PUT \ --user kvaughan:bribery \ --header "If-Match: 00000000b017c5b8" \ --header "Content-Type: application/json" \ --data '{ \ "contactInformation": { \ "telephoneNumber": "+1 408 555 1212", \ "emailAddress": "scarter@example.com" \ }, \ "name": { \ "familyName": "Carter", \ "givenName": "Sam" \ }, \ "userName": "scarter@example.com", \ "displayName": "Sam Carter", \ "groups": [ \ { \ "_id": "Accounting Managers" \ } \ ], \ "manager": [ \ { \ "_id": "trigden", \ "displayName": "Torrey Rigden" \ } \ ] \ }' \ http://opendj.example.com:8080/users/scarter?_prettyPrint=true { "_rev" : "00000000a1ee3da3", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "scarter@example.com" }, "_id" : "scarter", "name" : { "familyName" : "Carter", "givenName" : "Sam" }, "userName" : "scarter@example.com", "displayName" : "Sam Carter", "meta" : { "lastModified" : "2013-04-12T07:47:45Z" }, "groups" : [ { "_id" : "Accounting Managers" } ], "manager" : [ { "_id" : "trigden", "displayName" : "Torrey Rigden" } ] }

To delete a resource, perform an HTTP DELETE on the resource URL. On success, the operation returns the resource you deleted. $ curl \ --request DELETE \ --user kvaughan:bribery \ http://opendj.example.com:8080/users/newuser?_prettyPrint=true { "_rev" : "000000003a5f3cb2", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-04-11T09:58:27Z" }, "manager" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" } ] } To delete a resource only if the resource matches a particular version, use an If-Match: revision header. $ curl --user kvaughan:bribery http://opendj.example.com:8080/users/newuser?_fields=_rev {"_rev":"000000006d8d7358"} $ curl \ --request DELETE \ --user kvaughan:bribery \ --header "If-Match: 000000006d8d7358" \ http://opendj.example.com:8080/users/newuser?_prettyPrint=true { "_rev" : "00000000383f3cae", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-04-11T12:48:48Z" }, "manager" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" } ] } To delete a resource and all its children, you must change the configuration, get the REST LDAP gateway or HTTP Connection Handler to reload its configuration, and perform the operation as a user who has the access rights required. The following steps show one way to do this with the HTTP Connection Handler. In this case the LDAP view of the user to delete shows two child entries. $ ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&)" dn dn: uid=nbohr,ou=People,dc=example,dc=com dn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com dn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com In the configuration file for the HTTP Connection Handler, by default /path/to/opendj/config/http-config.json, set "useSubtreeDelete" : true. After this change, only users who have access to request a tree delete can delete resources. Force the HTTP Connection Handler to reread its configuration. $ dsconfig \ set-connection-handler-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "HTTP Connection Handler" \ --set enabled:false \ --no-prompt $ dsconfig \ set-connection-handler-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --handler-name "HTTP Connection Handler" \ --set enabled:true \ --no-prompt Delete as a user who has rights to perform a subtree delete on the resource. $ curl \ --request DELETE \ --user kvaughan:bribery \ http://opendj.example.com:8080/users/nbohr?_prettyPrint=true { "_rev" : "000000003d912113", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "nbohr@example.com" }, "_id" : "nbohr", "name" : { "familyName" : "Bohr", "givenName" : "Niels" }, "userName" : "nbohr@example.com", "displayName" : "Niels Bohr" }

OpenDJ lets you patch JSON resources, updating part of the resource rather than replacing it. For example, you could change Babs Jensen's email address by issuing an HTTP PATCH request, as in the example that follows. Notice that the data sent specifies the type of patch operation, the field to change, and a value that depends on the field you change and on the operation. A single-valued field takes an object, boolean, string, or number depending on its type, whereas a multi-valued field takes an array of values. Getting the type wrong results in an error. Also notice that the patch data is itself an array, since you could patch more than one part of the resource by using a set of patch operations in the same request. $ curl \ --user kvaughan:bribery \ --request PATCH \ --header "Content-Type: application/json" \ --data '[ \ { \ "operation": "replace", \ "field": "/contactInformation/emailAddress", \ "value": "babs@example.com" \ } \ ]' \ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true { "_rev" : "00000000f3fdd370", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "babs@example.com" }, "_id" : "bjensen", "name" : { "familyName" : "Jensen", "givenName" : "Barbara" }, "userName" : "babs@example.com", "displayName" : "Barbara Jensen", "meta" : { "lastModified" : "2013-05-13T14:35:31Z" }, "manager" : [ { "_id" : "trigden", "displayName" : "Torrey Rigden" } ] } OpenDJ supports four types of patch operation. "add" The add operation ensures that the target field contains the value provided, creating parent fields as necessary. If the target field is single-valued and a value already exists, then that value is replaced with the value you provide. Note that you do not get an error when adding a value to a single-valued field that already has a value. A single-valued field is one whose value is not an array (an object, string, boolean, or number). If the target field is multi-valued, then the array of values you provide is merged with the set of values already in the resource. New values are added, and duplicate values are ignored. A multi-valued field takes an array value. "remove" The remove operation ensures that the target field does not contain the value provided. If you do not provide a value, the entire field is removed if it already exists. If the target field is single-valued and a value is provided, then the provided value must match the existing value to remove, otherwise the field is left unchanged. If the target field is multi-valued, then values in the array you provide are removed from the existing set of values. "replace" The replace operation removes existing values on the target field, and replaces them with the values you provide. It is equivalent to performing a remove on the field, then an add with the values you provide. "increment" The increment operation increments or decrements the value or values in the target field by the amount you specify, which is positive to increment, negative to decrement. The target field must be a number or a set of numbers. The value you provide must be a single number. One key nuance in how patch works with OpenDJ has to do with multi-valued fields. Although JSON resources represent multi-valued fields as arrays, OpenDJ treats those values as sets. In other words, values in the field are unique, and the ordering of an array of values is not meaningful in the context of patch operations. If you reference array values by index, OpenDJ returns an error.OpenDJ does let you use a hyphen as the last element of the "field" JSON pointer value to add an element to the set, as in curl --user kvaughan:bribery --request PATCH --header "Content-Type: application/json" --data '[{ "operation" : "add", "field" : "/members/-", "value" : { "_id" : "bjensen" } }]' http://opendj.example.com:8080/groups/Directory%20Administrators. Instead use the patch operations as if arrays values were sets. For example, you can include Barbara Jensen in a group by adding her to the set of members. $ curl \ --user kvaughan:bribery \ --request PATCH \ --header "Content-Type: application/json" \ --data '[ \ { \ "operation": "add", \ "field": "/members", \ "value": [ \ { \ "_id": "bjensen" \ } \ ] \ } \ ]' \ http://opendj.example.com:8080/groups/Directory%20Administrators?_prettyPrint=true { "_rev" : "00000000b70c881a", "schemas" : [ "urn:scim:schemas:core:1.0" ], "_id" : "Directory Administrators", "displayName" : "Directory Administrators", "meta" : { "lastModified" : "2013-05-13T16:40:23Z" }, "members" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" }, { "_id" : "rdaugherty", "displayName" : "Robert Daugherty" }, { "_id" : "bjensen", "displayName" : "Barbara Jensen" }, { "_id" : "hmiller", "displayName" : "Harry Miller" } ] } Removing her from the group is similar. $ curl \ --user kvaughan:bribery \ --request PATCH \ --header "Content-Type: application/json" \ --data '[ \ { \ "operation": "remove", \ "field": "/members", \ "value": [ \ { \ "_id": "bjensen" \ } \ ] \ } \ ]' \ http://opendj.example.com:8080/groups/Directory%20Administrators?_prettyPrint=true { "_rev" : "00000000e241797e", "schemas" : [ "urn:scim:schemas:core:1.0" ], "_id" : "Directory Administrators", "displayName" : "Directory Administrators", "meta" : { "lastModified" : "2013-05-13T16:40:55Z" }, "members" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" }, { "_id" : "rdaugherty", "displayName" : "Robert Daugherty" }, { "_id" : "hmiller", "displayName" : "Harry Miller" } ] } You can use resource revision numbers in If-Match: revision headers to patch the resource only if the resource matches a particular version. $ curl \ --user kvaughan:bribery \ "http://opendj.example.com:8080/users/bjensen?_prettyPrint=true&_fields=_rev" { "_rev" : "00000000c1b6d4c7" } $ curl \ --user kvaughan:bribery \ --request PATCH \ --header "If-Match: 00000000c1b6d4c7" \ --header "Content-Type: application/json" \ --data '[ \ { \ "operation": "add", \ "field": "/contactInformation/emailAddress", \ "value": "babs@example.com" \ } \ ]' \ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true { "_rev" : "00000000f946d377", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "babs@example.com" }, "_id" : "bjensen", "name" : { "familyName" : "Jensen", "givenName" : "Barbara" }, "userName" : "babs@example.com", "displayName" : "Barbara Jensen", "meta" : { "lastModified" : "2013-05-13T16:56:33Z" }, "manager" : [ { "_id" : "trigden", "displayName" : "Torrey Rigden" } ] } The resource revision changes after you successfully perform the patch operation.

OpenDJ implements an action that lets the server set the resource ID on creation. To use this action, perform an HTTP POST with header Content-Type: application/json, _action=create in the query string, and the JSON content of your resource. The following example creates a new user entry. $ curl \ --request POST \ --user kvaughan:bribery \ --header "Content-Type: application/json" \ --data '{ \ "_id": "newuser", \ "contactInformation": { \ "telephoneNumber": "+1 408 555 1212", \ "emailAddress": "newuser@example.com" \ }, \ "name": { \ "familyName": "New", \ "givenName": "User" \ }, \ "displayName": "New User", \ "manager": [ \ { \ "_id": "kvaughan", \ "displayName": "Kirsten Vaughan" \ } \ ] \ }' \ "http://opendj.example.com:8080/users?_action=create&_prettyPrint=true" { "_rev" : "0000000034a23ca7", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-04-11T11:19:08Z" }, "manager" : [ { "_id" : "kvaughan", "displayName" : "Kirsten Vaughan" } ] }

To query resource collections, perform an HTTP GET with a _queryFilter=filter parameter in your query string. For query operations, your filter expressions are constructed from the following building blocks. Make sure you URL encode the filter expressions, which are shown here without URL encoding to make them easier to read. In these expressions the simplest json-pointer is a field of the JSON resource, such as userName or id. A json-pointer can however point to nested elements as described in the JSON Pointer Internet-Draft. Comparison expressions You can build filters using the following comparison expressions. json-pointer eq json-value Matches when the pointer equals the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+eq+"bjensen@example.com"' { "result" : [ { "_rev" : "00000000315fb731", "schemas" : [ "urn:scim:schemas:core:1.0" ], "manager" : [ { "_id" : "trigden", "displayName" : "Torrey Rigden" } ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "bjensen@example.com" }, "_id" : "bjensen", "name" : { "familyName" : "Jensen", "givenName" : "Barbara" }, "userName" : "bjensen@example.com", "displayName" : "Barbara Jensen" } ], "resultCount" : 1, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer co json-value Matches when the pointer contains the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+co+"jensen"&_fields=userName' { "result" : [ { "userName" : "ajensen@example.com" }, { "userName" : "bjensen@example.com" }, { "userName" : "gjensen@example.com" }, { "userName" : "jjensen@example.com" }, { "userName" : "kjensen@example.com" }, { "userName" : "rjensen@example.com" }, { "userName" : "tjensen@example.com" } ], "resultCount" : 7, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer sw json-value Matches when the pointer starts with the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+sw+"ab"&_fields=userName' { "result" : [ { "userName" : "abarnes@example.com" }, { "userName" : "abergin@example.com" } ], "resultCount" : 2, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer lt json-value Matches when the pointer is less than the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+lt+"ac"&_fields=userName' { "result" : [ { "userName" : "abarnes@example.com" }, { "userName" : "abergin@example.com" } ], "resultCount" : 2, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer le json-value Matches when the pointer is less than or equal to the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+le+"ad"&_fields=userName' { "result" : [ { "userName" : "abarnes@example.com" }, { "userName" : "abergin@example.com" }, { "userName" : "achassin@example.com" } ], "resultCount" : 3, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer gt json-value Matches when the pointer is greater than the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+gt+"tt"&_fields=userName' { "result" : [ { "userName" : "ttully@example.com" }, { "userName" : "tward@example.com" }, { "userName" : "wlutz@example.com" } ], "resultCount" : 3, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } json-pointer ge json-value Matches when the pointer is greater than or equal to the value, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName+ge+"tw"&_fields=userName' { "result" : [ { "userName" : "tward@example.com" }, { "userName" : "wlutz@example.com" } ], "resultCount" : 2, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } Presence expression json-pointer pr matches any resource on which the json-pointer is present, as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=userName%20pr' { "result" : [ { "_rev" : "000000002210a544", "schemas" : [ "urn:scim:schemas:core:1.0" ], "manager" : [ { "_id" : "scarter", "displayName" : "Sam Carter" } ], "contactInformation" : { "telephoneNumber" : "+1 408 555 9445", "emailAddress" : "abarnes@example.com" }, "_id" : "abarnes", "name" : { "familyName" : "Barnes", "givenName" : "Anne-Louise" }, "userName" : "abarnes@example.com", "displayName" : "Anne-Louise Barnes" },… many entries omitted … "_id" : "newuser", "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User", "meta" : { "created" : "2013-03-26T10:52:42Z" } } ], "resultCount" : 152, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } Literal expressions true matches any resource in the collection. false matches no resource in the collection. In other words you can list all resources in a collection as in the following example. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/groups?_queryFilter=true&_fields=displayName' { "result" : [ { "displayName" : "Accounting Managers" }, { "displayName" : "Directory Administrators" }, { "displayName" : "HR Managers" }, { "displayName" : "PD Managers" }, { "displayName" : "QA Managers" } ], "resultCount" : 5, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } Complex expressions You can combine expressions using boolean operators and, or, and ! (not), using parentheses, (expression), to group expressions. The following example queries resources with last name Jensen and manager name starting with Bar. Notice that the filters use the JSON pointers name/familyName and manager/displayName to identify the fields that are nested inside the name and manager objects. $ curl \ --user kvaughan:bribery \ 'http://opendj.example.com:8080/users?_queryFilter=\ (userName+co+"jensen"+and+manager/displayName+sw+"Sam")&_fields=displayName' { "result" : [ { "displayName" : "Jody Jensen" }, { "displayName" : "Ted Jensen" } ], "resultCount" : 2, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } You can page through search results using the following query string parameters. _pagedResultsCookie=string Opaque cookie used by the server to keep track of the position in the search results. In the request also set _pageSize greater than zero. You receive the cookie value from the server on the first request, and then supply the cookie value in subsequent requests until the server returns a null cookie, meaning that the final page of results has been returned. _pagedResultsOffset=integer When _pageSize is greater than zero, use this as an index in the result set indicating the page to return. When the value of _pagedResultsOffset is 1 or more, the server returns the page starting from the specified index. When _pagedResultsCookie is also set, the starting point is the position tracked by the cookie. Otherwise the offset is relative to the beginning of the result set. For example, _pageSize=2&_pagedResultsOffset=1 returns the third and fourth entries of the results. _pageSize=3&_pagedResultsOffset=2&_pagedResultsCookie=cookie returns the seventh, eighth, and ninth entries counting from the position tracked by the cookie. When _pageSize is not set, or when the value of _pagedResultsOffset is 0 or less, the setting has no effect. If other _pageSize is set, but the offset points to a page beyond the last of the search results, the result set returned is empty. _pageSize=integer Return query results in pages of this size, where integer should be greater than zero. Page sizes of zero or less have no effect, with the outcome that all results are returned, and _pagedResultsCookie is null in the response. After the initial request, use _pagedResultsCookie to page through the results. The following example demonstrates the use of paged results. The first call requests 5 results per page, and retrieves the first page. The next call provides the cookie to request the next 5 results. The final call provides the cookie and requests the 10th page of results after the last page of results specified by the cookie. $ curl \ --user bjensen:hifalutin \ "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5" { "result" : [ { "userName" : "abarnes@example.com" }, { "userName" : "abergin@example.com" }, { "userName" : "achassin@example.com" }, { "userName" : "ahall@example.com" }, { "userName" : "ahel@example.com" } ], "resultCount" : 5, "pagedResultsCookie" : "AAAAAAAAAA8=", "remainingPagedResults" : -1 } $ curl \ --user bjensen:hifalutin \ "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5\ &_pagedResultsCookie=AAAAAAAAAA8=" { "result" : [ { "userName" : "ahunter@example.com" }, { "userName" : "ajensen@example.com" }, { "userName" : "aknutson@example.com" }, { "userName" : "alangdon@example.com" }, { "userName" : "alutz@example.com" } ], "resultCount" : 5, "pagedResultsCookie" : "AAAAAAAAABQ=", "remainingPagedResults" : -1 } $ curl \ --user bjensen:hifalutin \ "http://opendj.example.com:8080/users?_queryFilter=true&_fields=userName&_pageSize=5\ &_pagedResultsCookie=AAAAAAAAAA8=&_pagedResultsOffset=10" { "result" : [ { "userName" : "gtriplet@example.com" }, { "userName" : "gtyler@example.com" }, { "userName" : "hmiller@example.com" }, { "userName" : "jbourke@example.com" }, { "userName" : "jbrown@example.com" } ], "resultCount" : 5, "pagedResultsCookie" : "AAAAAAAAAEY=", "remainingPagedResults" : -1 } Notice that "remainingPagedResults" : -1 in each case meaning that the number of remaining results is not known.