--- title: Conventions description: 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, shown here as accessToken, is accepted per RFC 6750 through the Authorization HTTP request header. For more information about acquiring a bearer access token for your organization, refer to Getting started. component: pingdirectory page_id: pingdirectory:directory:conventions canonical_url: https://developer.pingidentity.com/pingdirectory/directory/conventions.html section_ids: directory-rest-api-requests: Directory REST API requests authorization: Authorization http-methods: HTTP methods updating-a-resource: Updating a resource partial-updates-to-a-resource: Partial updates to a resource supported-data-exchange-formats: Supported data exchange formats link-expansion: Link expansion directory-rest-api-responses: Directory REST API responses http-response-headers: HTTP response headers http-response-codes: HTTP response codes synchronous-responses: Synchronous responses response-data-structure: Response data structure errors: Errors filtering-collections: Filtering collections attribute-tagging-rules: Attribute tagging rules reject-tagging-options-on-_dn-attributes-and-associated-naming-attribute: Reject tagging options on _dn attributes and associated naming attribute representation-of-user-attributes-with-tagging-options: Representation of user attributes with tagging options using-post-to-create-a-new-entry-containing-tagged-attributes: Using POST to create a new entry containing tagged attributes using-get-or-postsubtree-search-to-retrieve-existing-entries-containing-tagged-attributes: Using GET or POST/subtree /search to retrieve existing entries containing tagged attributes query-parameter-filtering: Query parameter filtering query-parameters-includeattributes-and-excludeattributes: "Query parameters 'includeAttributes' and 'excludeAttributes'" using-put-to-modify-an-existing-entry-containing-tagged-attributes: Using PUT to modify An existing entry containing tagged attributes using-patch-to-modify-existing-entries-containing-tagged-attributes: Using PATCH to modify existing entries containing tagged attributes --- # 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, shown here as `accessToken`, is accepted per [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) through the Authorization HTTP request header. For more information about acquiring a bearer access token for your organization, refer to [Getting started](getting-started.html). ### 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: ```none curl -X PATCH "https://ds.example.com/directory/v1/{{dn}}" \ -H "Content-type: application/json" \ -H "Authorization: Bearer accessToken" \ -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. ```none GET /directory/v1/uid=example.user,ou=people,dc=example,dc=com?expand=manager ``` The response data looks like this: ```json { "_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"] } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. ```json { "size": 3, "_links": { "self": { "href": "https:////directory/v1/schemas" } }, "_embedded": { "schemas": [ { "id": "5caa81af-ec05-41ff-a709-c7378007a99c", "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: ```json { "id": "4ffa81af-ec05-41ff-a709-c7378007a99c", "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'" } ] } ``` | Attribute | Required | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Yes | A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client (with server-side activity included for troubleshooting purposes). | | `code` | Yes | A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all services and is human readable (such as a defined constant rather than a number). | | `message` | Yes | A short description of the error. This message is intended to assist with debugging and is returned in English only. | | `details` | Yes | A detailed description of one or more errors returned as a result of the request. | ## 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. | Operator | Description | Behavior | | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | eq | equal | The attribute and operator values are not identical. | | ne | not equal | The attribute and operator values must be identical for a match. | | co | contains | The entire operator value must be a substring of the attribute value for a match. | | sw | starts with | The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical. | | ew | ends with | The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical. | | pr | present (has value) | If the attribute has a non-empty or non-null value, or if it contains a non-empty node for complex attributes, there is a match. | | ge | greater than or equal to | If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value. | | le | less than or equal to | If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value. | For more information about the SCIM Protocol Specification, refer to [SCIM Filtering](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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`:```none 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 accessToken' \ -d $'{ "filter": "objectClass eq \"person\" and sn eq \"Jones\"", "searchScope": "wholeSubtree", "limit": 20, "includeAttributes": "*,_operationalAttributes", "excludeAttributes": "sn,isMemberOf" }' ``` | ## Attribute tagging rules An LDAP attribute description that uses tagging options should be treated as a subtype of the same attribute type without the tagging option, inheriting from any parent attribute types. For example, `cn;region1` would be a subtype of `cn` and also of `name` since `cn` is a subtype of `name`. Likewise, `cn;region2` would be a different subtype of `cn` and `name`. The combined attribute description (the attribute type and tagging options) is not declared explicitly in the directory schema; only the attribute type is declared. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------- | | | An attribute type that **may** or **must** appear in an object class can be fulfilled by an attribute description with tagging options. | ### Reject tagging options on \_dn attributes and associated naming attribute The Directory REST API does not allow tagging options in the `_dn` attribute or associated naming attribute, since the Ping Directory Server does not support this for the underlying LDAP entries. If tagging is attempted, it returns a Code: 34 (invalid DN syntax) error. ```none { "_dn": "uid;x-opt=lindajones,oupeople,dc=example,dc=com", "uid;x-opt": "lindajones", } ``` ### Representation of user attributes with tagging options User attributes with tagging options appear in a separate JSON field from other attributes with the same type but different (or no) options. If there are multiple values with the same attribute type and tagging options, they will be represented as a JSON array. ### Using POST to create a new entry containing tagged attributes Tagged attributes are translated correctly into LDAP entries, including various permutations of the following: * Single-valued attributes of all supported types (string, integer, boolean, JSON), with no tagging option. * Multi-valued attributes of all supported types (string, integer, boolean, JSON), with no tagging option. * Single-valued attributes of all supported types (string, integer, boolean, JSON), tagged with a single option. * Multi-valued attributes of all supported types (string, integer, boolean, JSON), tagged with a single option. * Single-valued attributes of all supported types (string, integer, boolean, JSON), tagged with multiple options. * Multi-valued attributes of all supported types (string, integer, boolean, JSON), tagged with multiple options. ### Using GET or POST/subtree /search to retrieve existing entries containing tagged attributes Tagged attributes are translated correctly from LDAP entries, covering the same permutations for POST. Tagged attributes are returned correctly when returning multiple entries with the /subtree option. Tagged attributes are returned correctly for multiple entries with a cursored search option. #### Query parameter filtering Note that the [SCIM filter syntax](https://datatracker.ietf.org/doc/html/rfc7644) (section 3.4.2.2) does not allow semicolons in attribute names. The PingDirectory REST API supports the variant syntax 'REST API Filter syntax' (which is the SCIM filter syntax plus semicolons). If a filter clause specifies an attribute name with no tagging options, the filter applies to all attributes with that base name, tagged or untagged. If a filter clause specifies an attribute name with tagging options, the filter applies only to attributes with that base name and all of the specified tagging options. As specified in RFC 7644, if the specified attribute in a filter expression is a multi-valued attribute, the filter matches if any of the values of the specified attribute match the specified criterion. * `eq`: Matches if any applicable attribute has a value identical to the specified one. * `ne`: Matches if any applicable attribute has a value not identical to the specified one. * `co`, `sw`, `ew`: Matches if any applicable attribute has a value containing the specified substring, prefix, or suffix, respectively. * `gt`, `ge`, `lt`, `le`: Matches if any applicable attribute has a value greater than (or less than) the specified value. #### Query parameters 'includeAttributes' and 'excludeAttributes' Similarly, if the `includeAttributes` or `excludeAttributes` parameters specify an attribute name with no tagging options, the result includes or excludes all attributes of that type, tagged or untagged. If the query parameter specifies an attribute name with tagging options, the result includes or excludes only attributes with that exact name and tagging options. #### Using PUT to modify An existing entry containing tagged attributes Attributes modified using a `PUT` request should be specified using the exact name and tagging options. For example, the following only updates the value of `myAttr` and not `myAttr;x-opt-1`, or any other tagged attribute. ```none PUT /directory/v1/uid=lindajones,ou=people,dc=example,dc=com Content-Type: application/json Request Body { "myAttr": "new value for myAttr with no tagging options" } ``` Likewise, the following only updates the value of `myAttr;x-opt-2;x-opt-3` and not any of the others. ```none PUT /directory/v1/uid=lindajones,ou=people,dc=example,dc=com Content-Type: application/json Request Body { "myAttr;x-opt-2;x-opt-3": "new value for myAttr with x-opt-2 and x-opt-3" } ``` #### Using PATCH to modify existing entries containing tagged attributes Attributes to be updated using a `PATCH` request should be specified using the exact name and tagging options in the `attributeName` field. For `PATCH` "add" and "remove", only attributes with the exact name and tagging options are affected. However, using `PATCH` "set" with an untagged attribute name removes any tagged attributes.