The Directory REST API gives developers who are more comfortable with REST than LDAP access to arbitrary directory data in a way that ensures directory data remains consistent regardless of whether it is accessed from LDAP or REST. The Directory API is enabled during server setup. After setup, individual services and applications can be enabled or disabled by configuring the HTTPS Connection Handler.

While both the Directory REST API and System for Cross-domain Identity Management (SCIM) provide REST access to directory data, the goals of the two protocols are different. SCIM is useful to generic, external clients that require simple, narrow access to identity data, but because it is a less common standard for identity stores, it might not offer as much functionality or be as user-friendly as the Directory REST API.

The Directory REST API can be used for the following operations.

HTTP operation Resource endpoint Description Allowed query parameters

DELETE

/directory/v1/{dn}

Delete an entry.

GET

/directory/v1

Get metadata about the API and server.

GET

/directory/v1/{dn}

Retrieve a single entry.
  • expand
  • includeAttributes
  • excludeAttributes

GET

/directory/v1/{dn}/subtree

Search an entry's descendants.
  • filter
  • searchScope
  • cursor
  • limit
  • includeAttributes
  • excludeAttributes

GET

/directory/v1/schemas

Retrieve the schemas of all available object classes.

GET

/directory/v1/schemas/{objectclass}

Retrieve schema for a specific object class.

GET

/directory/v1/schemas/_operationalAttributes

Retrieve schema for operational attributes.

GET

/directory/v1/me

Alias for retrieving the current user.

PATCH

/directory/v1/{dn}

Modify an entry (add or delete values).

expand

POST

/directory/v1

Create a new entry.

expand

PUT

/directory/v1/{dn}

Modify or rename an entry.

expand
  • Configure the Directory REST API with any of the following properties using dsconfig:
    CommandDescription
    basic-auth-enabled Specifies whether users can connect to the service with HTTP Basic authentication. If disabled, users need a bearer token. If changed, the server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled. Basic authentication is enabled by default.
    identity-mapper If HTTP Basic authentication is enabled, the identity mapper referenced by this distinguished name (DN) must be used to map the user names provided to user entries. By default, an identity mapper is provided, which maps a fully-qualified DN to an entry. For changes to take effect, the server must be restarted, or any HTTP connection handlers referencing this service disabled and re-enabled.
    access-token-validator Specifies the subset of this server’s Access Token Validators (by DN), which can validate Bearer authentication tokens. By default, if no validators are specified, then any of the validators on the server can be used. For changes to take effect, the server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled.
    access-token-scope The scope that must be present in Bearer tokens in order to be accepted by this service. If no value is provided, Bearer token authentication is disabled, and only Basic authentication is used. By default, no value is provided. Changes to this value take effect immediately.
    audience A string or URI audience that must be present in Bearer tokens in order to be accepted by this service. If no value is provided, any audience is acceptable. By default, no value is provided. Changes to this value take effect immediately.
    max-page-size The maximum number of entries to be returned in one page from the search endpoint. Actual results returned might be lower due to the limit query parameter on the request and the actual number of available results. The value must be an integer between 1 and 1000. The default value is 100. Changes to this value take effect immediately.
    schemas-endpoint-objectclass The list of object classes that will be returned by the /schemas/ endpoint in the REST API. By default, no schemas are returned. Changes to this value take effect immediately.

    The following example uses dsconfig to configure an objectClass entity.

    dsconfig set-http-servlet-extension-props --extension-name "Directory REST API" \
  --add schemas-endpoint-objectclass:ubidPerson