JSON REST OpenDJ lets you access directory data as JSON resources over HTTP. To configure this capability, see REST Client Access for instructions. This chapter demonstrates basic RESTful client operations using the default configuration and sample directory data imported into OpenDJ from Example.ldif.

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.

TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-694

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 --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" }' http://opendj.example.com:8080/rest2ldap/users/newuser?_prettyPrint=true { "id" : "newuser", "rev" : "0000000049522179", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" }, "name" : { "familyName" : "New", "givenName" : "User" }, "userName" : "newuser@example.com", "displayName" : "New User" } 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 http://opendj.example.com:8080/rest2ldap/users/bjensen?_prettyPrint=true { "id" : "bjensen", "rev" : "000000002f43b789", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "bjensen@example.com" }, "name" : { "familyName" : "Jensen", "givenName" : "Barbara" }, "userName" : "bjensen@example.com", "displayName" : "Barbara Jensen" }

TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-693

TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-692

TODO, https://bugster.forgerock.org/jira/browse/CREST-3

OpenDJ implements an action that lets the server choose 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. Lines are folded for readability. TODO, fix pending https://bugster.forgerock.org/jira/browse/OPENDJ-775 $ curl --request POST --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" }' http://opendj.example.com:8080/rest2ldap/users?_action=create&_prettyPrint=true { "id": "newuser", "rev": "0000000049522179", "schemas": [ "urn:scim:schemas:core:1.0" ], "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" }, "name": { "familyName": "New", "givenName": "User" }, "userName": "newuser@example.com", "displayName": "New User" } TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-695

To query resource collections, perform an HTTP GET with a _filter=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. Request URLs are folded in the following examples to make them easier to read. json-pointer eq json-value Matches when the pointer equals the value, as in the following example. $ curl 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+eq+"bjensen@example.com" &_prettyPrint=true' { "result" : [ { "id" : "bjensen", "rev" : "000000002f43b789", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { "telephoneNumber" : "+1 408 555 1862", "emailAddress" : "bjensen@example.com" }, "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+co+"jensen" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+sw+"ab" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+lt+"ac" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+le+"ad" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+gt+"tt" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName+ge+"tw" &_fields=userName &_prettyPrint=true' { "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 'http://opendj.example.com:8080/rest2ldap /users?_filter=userName%20pr&_prettyPrint=true' { "result" : [ { "id" : "abarnes", "rev" : "000000002609a565", "schemas" : [ "urn:scim:schemas:core:1.0" ], "contactInformation" : { ... many entries omitted ... "userName" : "fdupont@example.fr", "displayName" : "Frederique Dupont" } ], "resultCount" : 151, "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 http://opendj.example.com:8080/rest2ldap/users?_filter=true ... much output omitted ... 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 first name starting with Bar. Notice that the filters use the JSON pointers name/familyName and name/givenName to identify the fields that are nested inside the name object. $ curl 'http://opendj.example.com:8080/rest2ldap /users?_filter=(name/familyName+eq+"jensen"+and+name/givenName+sw+"Bar") &_fields=name &_prettyPrint=true' { "result" : [ { "name" : { "familyName" : "Jensen", "givenName" : "Barbara" } } ], "resultCount" : 1, "pagedResultsCookie" : null, "remainingPagedResults" : -1 } You can have the server sort JSON resources before it returns them by using the _sortKeys[+-]=field[,...] query string. TODO, pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-702 You can page through search results using the following query string parameters. TODO, pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-701 __pagedResultsCookie=string __pagedResultsOffset=string __pagedResultsCookie=string