Directory entry endpoints


Overview

The Directory REST API includes endpoints perform create, read, update, and delete operations on PingDirectory Server entries. Entries are identified in the request URL by their distinguished name {dn}.

Directory entry endpoint operations

Endpoint Examples

In the following examples, an attribute is represented as a key/value pair within the entry JSON object. Attribute values are given as either a single JSON value, or as an array of JSON values, according to whether the attribute is single-valued or multi-valued in the schema.

Individual values can be one of four types: string, integer, boolean, or JSON object. Floating point numbers should be provided as strings since LDAP does not support floating point numbers. Dates are provided in the ISO-8601 format, and binary values are represented as Base64-encoded strings.

Example:

"createTimestamp": "2018-05-01T15:04:49.866Z"
"ubidEmailJSON": [
  {
    "type": "work",
    "value": "ljones@example.com"
  }
]

Attribute names are always case sensitive and must be specified in the exact form as they appear in the schema. These rules apply for both request and response entities.

Get server metadata

A GET request on the base endpoint, /directory/v1, returns metadata about the server and API. It also returns a list of configured schemas allowed on the server. The following sample shows the GET /directory/v1 operation.

curl -X "GET" "https://ds.example.com/directory/v1" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

When successful, the operation returns a 200 OK message and the response data looks like this:

{
   “vendorName”: “Ping Identity Corporation”,
   “vendorVersion”: “Ping Identity Directory Server 7.2.0.0”,
   “startupUUID”: “cb1ee26d-683d-43b9-817b-f41ffe68d21c”,
   “startTime”: “20181108171520Z”,
   “publicBaseDNs”: [
       “dc=example,dc=com”
   ],
   “_links”: {
       “schemas”: {
           “href”: “https://127.0.0.1:1443/directory/v1/schemas”
       },
       “self”: {
           “href”: “https://127.0.0.1:1443/directory/v1/”
       },
       “publicBaseDNs”: [
           {
               “href”: “https://127.0.0.1:1443/directory/v1/dc=example,dc=com”
           }
       ]
   }
}

Create an entry

The POST /directory/v1 operation adds a new entry to the directory. The request body must contain all of the required attributes as defined in the schema. If there are no required attributes defined in the schema, you can submit a valid create request with only the _dn attribute in the request body.

The following sample shows a create request for a schema that requires the objectClass attribute value in the request body.

curl -X "POST" "https://ds.example.com/directory/v1" \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer jwtToken' \
  -d $'{
    "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
    "objectClass": [ "top", "ubidPerson"]
    }'

When successful, the response returns a 201 Created message. The data looks like this:

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "ubidPerson" ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/ubidPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}

Create a new entry and generate an entryUUID

You can create a new entry using the parent DN. The response shows the entry data, including the generated entryUUID attribute value associated with the entry resource. The entryUUID can be used to reference the entry, keeping confidential information from appearing in the DN.

curl -X "POST" "https://ds.example.com/directory/v1" \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer jwtToken' \
  -d $'{
  "_parentDN": "ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"]
  }'

The response data looks like this:

{
  "_dn": "entryUUID=a4fbd3ca-f7a0-42f2-af66-13f2c0dd8cd1,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/entryUUID=a4fbd3ca-f7a0-42f2-af66-13f2c0dd8cd1,ou=people,dc=example,dc=com"
    }
  }
}

Get an entry

The following sample shows the GET /directory/v1/{dn} operation to return the directory entry specified by its distinguished name (dn).

Note: This endpoint accepts the expand, includeAttributes, and excludeAttributes query parameters.

curl -X "GET" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "ubidPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"],
  "ubidEmailJSON": [
    {
      "type": "work",
      "value": "ljones@example.com"
    },
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/ubidPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}

Include or exclude attributes

By default, endpoints that retrieve and list entry data return all user attributes and no operational attributes (unless the server is configured to return specified operational attributes by default). The GET /directory/v1/{dn} endpoint also supports fine-tuning the response data through the following request parameters:

  • includeAttributes

    Specifies the attribute or attributes in the entry that should be included in the response.

  • excludeAttributes

    Specifies the attribute or attributes in the entry that should be excluded in the response.

These request parameters accept a comma-separated list of attributes to either include or exclude from the response entries. They also support the following aliases as values:

  • *

    Refers to all user attributes of the resource.

  • _operationalAttributes

    Refers to all operational attributes of the resource.

Note: If the same attribute is provided in both includeAttributes and excludeAttributes, an error is returned. When the * alias is used, the excludeAttributes parameter takes precedence. For example, includeAttributes=*&excludeAttributes=sn returns all user attributes except sn, but excludeAttributes=*&includeAttributes=sn returns no attributes (except DN).

The following sample shows the GET /directory/v1/{dn} operation to return the base entry and all user attributes for the entry, but exclude sn.

curl -X "GET" "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com" \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer jwtToken' \
  -d $'{
    "searchScope": "baseObject",
    "includeAttributes": "*",
    "excludeAttributes": "sn"

  }'

The response data looks like this:

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "uid": ["lindajones"],
  "cn": [ "Linda Jones", "Linda F. Jones" ],
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "createTimestamp": "2018-05-01T15:04:49.866Z",
  "modifyTimestamp": "2018-05-01T15:04:51.591Z",
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/entryUUID=a4fbd3ca-f7a0-42f2-af66-13f2c0dd8cd1,ou=people,dc=example,dc=com"
    }
  }
}

Update an entry

The PUT /directory/v1/{dn} endpoint modifies the entry specified by its distinguished name. Attribute values specified in the request body are updated; existing attributes omitted from the request maintain their current values. Attribute values set to null in the request body are removed from the entry.

Attributes designated for update are replaced entirely. You cannot partially modify an attribute. In addition, PUT operates exclusively on top-level attributes of the entity. If you wish to edit an attribute value within a JSON entity, you must replace the entire entity. Providing a null value for an attribute within a JSON entity removes the entity.

Note: It is not possible to modify any API attributes such as _links, _embedded, or _parentDN.

curl -X "PUT" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "cn": [ "Linda Jones", "Linda F. Jones" ],
  "ubidEmailJSON": null
}'

The response data looks like this:

{
  "_dn": "entryUUID=a4fbd3ca-f7a0-42f2-af66-13f2c0dd8cd1,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindajones"],
  "cn": [ "Linda Jones", "Linda F. Jones" ],
  "sn": ["Jones"],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/entryUUID=a4fbd3ca-f7a0-42f2-af66-13f2c0dd8cd1,ou=people,dc=example,dc=com"
    }
  }
}

Note: To update the DN of an entry, see Rename or move an entry.

Update an entry (LDAP modify)

The PATCH /directory/v1/{dn} endpoint functions just like an LDAP ldapmodify operation. Similar to the PUT update operation, the PATCH operation does not allow partial changes to a JSON object.

The request body requires the modificationType property, which supports the following four types of modifications:

  • add

    Adds the attribute value (or values) specified in the values property.

  • remove

    Removes the attribute value (or values) specified in the values property.

  • set

    Replaces all the values in the specified attribute with the value (or values) specified in values property.

  • increment

    Changes the integer value of the attribute by the amount specified in the values property. The request values should contain a single number, and the attribute must be a single-value or a multiple value integer type. If the attribute is a multiple values integer type, the increment gets applied to all the values. For example, if the attribute had [1, 2] before the increment and the increment had values of 5, then after the increment, the attribute would have [6,7].

Note: If the values property is null or an empty array, the update depends on the modification type: set removes the attribute entirely; remove and increment return an error; add is an LDAP No-Op that does not change the directory. It is not possible to modify any API attributes such as _links, _embedded, _dn, or _parent using PATCH.

curl -X "PATCH" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "modifications": [
    {
      "attributeName": "cn",
      "modificationType": "add",
      "values": [
        "Linda F. Jones"
      ]
    },
    {
      "attributeName": "cn",
      "modificationType": "remove",
      "values": [
        "Linda Jones"
      ]
    },
    {
      "attributeName": "manager",
      "modificationType": "set",
      "values": [
        "Boss",
        "Vice Boss"
      ]
    },
    {
      "attributeName": "salary",
      "modificationType": "increment",
      "values": 20000
    },
    {
      "attributeName": "ubidEmailJSON",
      "modificationType": "add",
      "values": [
        {"type": "home", "value": "user@example.com", "verified": true}
      ]
    }
  ]
}'

The response data looks like this:

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda F. Jones"],
  "sn": ["Jones"],
  "manager": [ "Boss", "Vice Boss" ],
  "salary": [120000],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}

Rename or move an entry

The PUT /directory/v1/{dn} endpoint functions like an LDAP moddn operation for moving or renaming one LDAP entry when the _dn attribute is included in the request. To change the DN of an entry, both the new DN and the naming attribute, the attribute used in the entry’s RDN (relative distinguished name), must be present in the specified entry, even if the naming attribute is not changing. This rename operation can be in the same request as other attributes are modified. However, an error from either the rename or the modify portions of the request causes the entire operation to fail.

Note: If an entry is renamed and modified in one request, a Multi-Update Request Extended Request (OID 1.3.6.1.4.1.30221.2.6.17) is used. The request can fail if no ACI is created to allow a user to use this request, even if the user has permission to perform modify and rename operations independently. The following sample shows a multi-update ACI:

(extop="11.3.6.1.4.1.30221.2.6.17")(version 3.0; acl "Grant access to the Multi Update Extended Request for the rest-api-client account"; allow (all) userdn="ldap:///uid=rest-api-client,o=example";)

Change the name

You can use the PUT /directory/v1/{dn} operation to change the name associated with the specified entry from Linda Jones to Linda Smith.

curl -X "PUT" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "_dn": "uid=lindasmith,ou=people,dc=example,dc=com",
  "uid": ["lindasmith"],
  "cn": ["Linda Smith"],
  "sn": ["Smith"]
}'

The response data looks like this:

{
  "_dn": "uid=lindasmith,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindasmith"],
  "cn": ["Linda Smith"],
  "sn": ["Smith"],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindasmith,ou=people,dc=example,dc=com"
    }
  }
}

Change the naming attribute, keep both

You can also execute an operation that keeps the old value of the naming attribute in place, which results in assigning multiple naming attribute values to the entry:

curl -X "PUT" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "_dn": "uid=lindasmith,ou=people,dc=example,dc=com",
  "uid": ["lindasmith", "lindajones"]
}'

The response data looks like this:

{
  "_dn": "uid=lindasmith,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindasmith", "lindajones"],
  "cn": ["Linda Smith"],
  "sn": ["Smith"],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}

Change the naming attribute

In addition, it is possible to change the attribute that is used as the naming attribute. In this case, both attribute options must be defined in the entry.

Note: This operation allows that both attributes can change, either one or the other attributes can change, or no attributes can change.

curl -X "PUT" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "_dn": "cn=Linda Brown,ou=people,dc=example,dc=com",
  "uid": ["lindabrown"],
  "cn": ["Linda Brown"],
  "sn": ["Brown"]
}'

The response data looks like this:

{
  "_dn": "cn=Linda Brown,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindabrown"],
  "cn": ["Linda Brown"],
  "sn": ["Brown"],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/cn=Linda+Brown,ou=people,dc=example,dc=com"
    }
  }
}

Modify the parent DN

You can also change the parent DN, in addition to or independent of the RDN, in order to move the entry. The new parent DN must point to an existing entry and the naming attribute must still be provided, even if the RDN does not change.

curl -X "PUT" "https://ds.example.com/directory/v1/cn=Linda+Brown,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "_dn": "cn=Linda Brown,ou=employees,dc=example,dc=com",
  "cn": ["Linda Brown"]
}'

The response data looks like this:

{
  "_dn": "cn=Linda Brown,ou=employees,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindabrown"],
  "cn": ["Linda Brown"],
  "sn": ["Brown"],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/cn=Linda+Brown,ou=employees,dc=example,dc=com"
    }
  }
}

You can also modify other attributes in addition to the parent DN in this request.

curl -X "PUT" "https://ds.example.com/directory/v1/cn=Linda+Brown,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "cn": ["Linda Jones"],
  "uid": ["lindajones"],
  "sn": ["Jones"]
}'

The response data looks like this:

{
  "_dn": "cn=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"],
  "ubidEmailJSON": [
    {
      "type": "home",
      "value": "user@example.com",
      "verified": true
    }
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}

Delete an entry

The following sample shows the DELETE /directory/v1/{dn} operation to delete the entry specified by its distinguished name from the directory.

curl -X "DELETE" "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

When successful, the response returns a 204 NO CONTENT message.

Note: Only one entry can be deleted in a delete operation. Subtree delete is not supported. Delete operations on an entry with children results in a 400 BAD REQUEST response.

Get the current user

In addition to retrieving a specified resource by providing the distinguished name, you can get the record of the currently authenticated user by calling the alias GET /directory/v1/me.

curl -X "GET" "https://ds.example.com/directory/v1/me" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_dn": "uid=lindajones,ou=people,dc=example,dc=com",
  "objectClass": [ "top", "ubidPerson" ],
  "uid": ["lindajones"],
  "cn": ["Linda Jones"],
  "sn": ["Jones"],
  "ubidEmailJSON": [
    {
      "type": "work",
      "value": "ljones@example.com"
    },
  ],
  "_links": {
    "schemas": [
      {
        "href": "https://ds.example.com/directory/v1/schemas/ubidPerson"
      }
    ],
    "self": {
      "href": "https://ds.example.com/directory/v1/uid=lindajones,ou=people,dc=example,dc=com"
    }
  }
}