Conventions

Directory REST API requests

Authorization

To make a call to the Directory REST API, you can use basic authentication (username/password) or an OAuth 2.0 access token for API authentication. The access token is accepted per RFC 6750 through the Authorization HTTP request header. For more information about acquiring a bearer access token for your organization, see Getting started.

HTTP methods

The Directory REST API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED error in the response.

• POST

  Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.

• PUT

  Updates attribute values specified by the user for the identified resource. Unspecified attributes are ignored.

• PATCH

  Updates only the attribute values specified by the user for the identified resource. Unspecified attributes are ignored.

• GET

  Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.

• DELETE

  Deletes or unlinks a resource from the collection.

Updating a resource

Requests submitted using PUT update attribute values of the resource specified in the request. You can explicitly clear an entry by specifying null for the attribute or by specifying an empty array in the case of multi-value attributes.

Partial updates to a resource

A PATCH operation performs updates of a resource, similar to that of a PUT operation. In addition, it allows updates to one item in a multi-value attribute. Omitting an attribute in a PATCH operation results in the attribute being ignored.

For set actions, you can use a value of null to explicitly clear the value. For remove actions, you must specify the value to remove.

Supported data exchange formats

The Directory REST API supports JSON as the data exchange format. The Content-type request header for the API call identifies the format of the request body for PUT, POST, and PATCH operations. The following sample identifies JSON as the data exchange type:

curl -X PUT "https://ds.example.com/directory/v1/{dn}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "param1" : "value1",
  "param2" : "value2"
}"

Link expansion

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request. The allowed values for the expand parameter are found in a resource’s _links field (not including “self”). Unrecognized values are ignored. Multiple values are separated using the comma character.

Here is a sample request that uses the expand parameter to provide an inline representation of the manager resource in the _embedded field.

GET /directory/v1/uid=example.user,ou=people,dc=example,dc=com?expand=manager

The response data looks like this:

{
    "_dn": "uid=example.user,ou=People,dc=example,dc=com",
    "_embedded": {
        "manager": {
            "_dn": "uid=manager,ou=People,dc=example,dc=com",
            "cn": ["Manager User"],
            "givenName": ["Manager"],
            "objectClass": [
                "top",
                "person",
                "organizationalPerson",
                "inetOrgPerson"
            ],
            "sn": ["User"],
            "uid": ["manager"]
        }
    },
    "_links": {
        "manager": {
            "href": "https://ds.example.com/directory/v1/uid=manager,ou=people,dc=example,dc=com"
        },
        "schemas": [
            {
                "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
            }
        ],
        "self": {
            "href": "https://ds.example.com/directory/v1/uid=example.user,ou=People,dc=example,dc=com"
        }
    },
    "cn": ["Example User"],
    "givenName": ["Example"],
    "manager": ["uid=manager,ou=people,dc=example,dc=com"],
    "objectClass": [
        "top",
        "person",
        "organizationalPerson",
        "inetOrgPerson"
    ],
    "sn": ["User"],
    "uid": ["example.user"]
}

Note: If available, you can specify multiple resources to expand in the query string by listing multiple attribute names separated by commas. In addition, if an element does not expand as expected, check the link to make sure the attribute name is specified accurately, particularly for case-sensitive attributes.

Directory REST API responses

HTTP response headers

The Directory REST API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

• Access-Control-Allow-Headers

  This header is used in response to a preflight request to indicate that HTTP headers can be used when making a request.

• Access-Control-Allow-Max-Age

  This header specifies how long the results of a preflight request can be cached.

• Access-Control-Allow-Methods

  This header specifies specifies the method or methods allowed when accessing the resource in response to a preflight request.

• Content-Type

  This header specifies the data exchange format for the response data. The value is application/HAL+json for successful operations and application/json for errors.

• Date

  This header specifies the date the response was sent.

HTTP response codes

The Directory REST API returns the status of an operation as a registered HTTP response code. The HTTP response codes are:

• 200-299

  Confirms a successful call.

• 300-399

  Indicates that the call or subsequent calls should be made to another resource.

• 400-499

  Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.

• 500-599

  Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

Operations may also return additional information about a failed operation in the HTTP response body.

Synchronous responses

Responses for synchronous operations have the following behavior:

• GET operations

  A request that returns a body also returns the code 200 OK with the resource in the body of the response.

• POST operations

  A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource. A POST operation that does not create a resource, such as POST /directory/v1/{dn}/subtree/search, returns a 200 OK message.

• PUT or PATCH operations

  A request that updates a resource returns 200 OK and the full resource in the body.

• DELETE operations

  A request that deletes a resource returns 204 NO CONTENT and no body.

Response data structure

All Directory REST API endpoints return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the Directory REST API result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.

{
    "size": 3,
    "_links": {
        "self": {
            "href": "https://<server>//directory/v1/schemas"
        }
    },
    "_embedded": {
        "schemas": [
            {
                "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
                "name": "SchemaName",
                "description": "Schema 1 description",
              }
          ...

For collections, the result data returns a size attribute, and all API requests return a self URL under the _links attribute that identifies the URI of the main resource. The _embedded attribute lists all the results in the collection.

These relationships and references are represented as follows:

• Links are represented using JSON HAL conventions (such as, in a _links object).

• Links are represented as absolute URLs.

• Links can be expanded using the expand parameter. The links can also be referenced via the “property-as-resource” pattern.

• References as attributes have an id value and may also have additional attributes.

Errors

Errors generated by the Directory REST API provide high-level information about the error, including an id, code, and the error message. Error responses also include a details attribute that provides specific information about one or more errors that occurred with the request. The response payload is formatted as follows:

{
   “id”: “c88cdaa8-078e-4448-a4c0-0d183941f8e4",
   “code”: “INVALID_DATA”,
   “message”: “Errors occurred while processing the request”,
   “details”: [
       {
           “code”: “REQUEST_FAILED”,
           “message”: “Entry ‘cn=Linda MissingFieldSN,ou=people,dc=example,dc=com’ violates the Directory Server schema configuration because it is missing attribute ‘sn’ which is required by object class ‘person’”
       }
   ]
}

Filtering collections

Requests that are known to return a large number of items can be filtered using the filter query string parameter. The following SCIM protocol filtering operators are supported.

For more information about the SCIM Protocol Specification, see SCIM Filtering.

Note: For searches using POST, the filter expression is placed in the request body, and the expression syntax requires escaping of quotes and spaces. The following sample shows a SCIM filtering expression that returns a list of entries that include an sn attribute value of Jones:

curl -X "POST" "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree/search" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "filter": "objectClass eq \"person\" and sn eq \"Jones\"",
  "searchScope": "wholeSubtree",
  "limit": 20,
  "includeAttributes": "*,_operationalAttributes",
  "excludeAttributes": "sn,isMemberOf"
}'