The Directory REST API is the native interface for client access to the PingDirectoryProxy Server. 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 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 may not offer as much functionality or be as easy to use as the Directory REST API.

Rather than trying to manage directory hierarchy or require attribute mapping, the Directory REST API provides direct access to directory data in a way that is dynamic, discoverable, and efficient.

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 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

The Directory REST API has the following properties, and can be configured with dsconfig:

  • basic-auth-enabled: Specifies whether users can connect to the service with HTTP Basic authentication. If disabled, users will need a Bearer token. If changed, the server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled. Basic auth is enabled by default.
  • identity-mapper: If HTTP Basic authentication is enabled, the identity mapper referenced by this 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. The server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled for changes to take effect.
  • access-token-validator: Specifies the subset of this server’s Access Token Validators (by DN), which may be used to validate Bearer authentication tokens. By default, if no validators are specified, then any of the validators on the server may be used. The server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled for changes to take effect.
  • access-token-scope: The scope which 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 can be 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 may 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