The HTTP-based Directory REST API supports directory server operations to create, read, update and delete any object in the directory using JSON over HTTP. For developers who are more familiar with REST than LDAP, the Directory REST API provides access to directory data in a way that ensures that the data remains consistent regardless of whether it is accessed from LDAP or REST.
The Directory REST API provides a known alternative to the existing SCIM API for access to directory data. Moreover, the benefits of the two protocols are different. SCIM is useful to generic, external clients that require simple, narrow access to identity data. Because SCIM is a least-common-denominator standard across a range of identity stores, it cannot be as feature rich or as natural to use to access directory data as the Directory REST API. In contrast, the Directory REST API provides high-performance direct access to hierarchical directory data in a way that is dynamic and discoverable, unlike SCIM, which abstracts away directory hierarchy or requires attribute mapping.
The Directory REST API service includes the following entities.
The directory service endpoints provide operations to search, add, modify, and delete entries. Entries are identified by their distinguished name {dn}.
To retrieve entries under a subtree of an entry, the directory service includes the {dn}/subtree endpoint to return the complete list. This endpoint requires the searchScope parameter, and response data for all requests are paged.
In addition to retrieving the current resource by DN, the directory service also supports the /directory/v1/me endpoint to return the entry of the currently authenticated user (without specifying the distinguished name of the entry).
A schema is the set of directory server rules that define the structures, contents, and constraints of a Directory Information Tree (DIT). The schema guarantees that any new data entries or modifications meet and conform to these predetermined set of definitions. It also reduces redundant data definitions and provides a uniform method for clients or applications to access its Directory Server objects. The PingDirectory Server ships with a default set of read-only schema files that define the core properties for the directory server.
Schemas endpoints provide operations to get all defined schemas and to find the schema associated with a specific objectClass.
The Directory REST API represents resources using JSON. Non-error responses are sent using the application/hal+json media type. Error responses are sent using the application/json media type.
Resources served by the Directory REST API follow the conventions of the JSON HAL (Hypertext Application Language) specification. Resources use the application/hal+json media type and can include the following read-only fields.
_links
An object whose fields are link objects (or arrays of link objects) that refer to related resources. Every resource includes a link object called self, which refers to the resource itself.
_embedded
An object whose fields contain embedded related resources. This field never appears by default but can be included if the client specifies the expand parameter. For more information, see Conventions.
A link object may contain the following fields.
href
The related resource’s URI.
The Directory REST API supports tagged attribute names as described in RFC-4512 Lightweight Directory Access Protocol (LDAP): Directory Information Models. Attribute types may be followed by a semicolon-separated list of tagging options. For example:
myAttr: An attribute of type ‘myAttr’ with no tagging options.
myAttr;opt-1: An attribute of type ‘myAttr’ with tagging option ‘opt-1’.
myAttr;opt-2;opt-3: An attribute of type ‘myAttr’ with multiple tagging options ‘opt-2’ and ‘opt-3’.
myAttr;opt-4: The first value for multi-valued attribute of type ‘myAttr’ with tagging option ‘opt-4’.
myAttr;opt-4: The second value for multi-valued attribute of type ‘myAttr’ with tagging option ‘opt-4’.
For detailed information about attribute tagging, see Conventions.