Platform APIs
More PingIdentity APIs

Subtree endpoints

Overview

The Directory REST API includes operations to retrieve a list of entries under a subtree of an entry, and to search the subtree using a POST request to avoid placing confidential information in the request URI.

Subtree endpoint operations

Endpoint Examples

List all entries

To retrieve a list of entries under a subtree of an entry, use the {dn}/subtree endpoint. This endpoint requires the searchScope parameter. The supported search scopes are:

  • baseObject

    Returns only the object directly described by the base DN.

  • singleLevel

    Returns only the entries that are immediate children of the base entry.

  • wholeSubtree

    Returns the base entry and all of its descendants.

  • subordinateSubtree

    Returns the descendants of the base entry, but not the base entry itself.

All list requests are paged. The limit parameter specifies the page size. However, the page size can be smaller than requested, either because the server has a configured maximum page size or because you have reached the last page and there are not enough entries to fill the page.

The next link enables navigation forward from the current page to the next page. The directory service does not support a previous link to move backward from the current page.

The size value on the returned object shows the actual number of entries returned in the request.

The following sample shows the GET /directory/v1/{dn}/subtree operation to return the base entry and all of its descendants.

curl -X "GET" "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "searchScope": "wholeSubtree",
  "limit": "100"
}'

The response data looks like this:

{
  "size": 100,
  "_embedded": {
    "entries": [
      {
        "_dn": "uid=lindajones,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/uid=lindajones,ou=people,dc=example,dc=com"
          }
        }
      },

      ... 99 more entries ...

    ]
  },
  "_links": {
    "self": {
      "href": "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree?searchScope=wholeSubtree&limit=100"
    },
    "next": {
      "href": "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree?limit=100&cursor=eyJjb29raWUiOiJ1c2VyMTAiLCJmaWx0ZXIiOiIiLCJzY29wZSI6Indob2xlU3VidHJlZSJ9"
    }
  }
}

Note: The searchScope parameter value is encoded in the cursor parameter in the next link URL. The search scope does not need to be provided on subsequent requests. This endpoint also accepts the includeAttributes and excludeAttributes query parameters. For more information about these query parameters, see Get an entry.

Filter search entries

The GET /directory/v1/{dn}/subtree endpoint supports a SCIM filtering parameter to limit the returned result set to those entries meeting the specified criteria. For example, the request below uses the filter objectClass eq "person" and sn eq "Jones" to search for all people with the last name of Jones.

curl -X "GET" "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "searchScope": "wholeSubtree",
  "filter": "objectClass%20eq%20%22"person%22%20and%20sn%20eq%20%22Jones%22"
}'

Filtering is done before pagination of the response data. The filter parameter is encoded into the cursor pagination parameter; it only needs to be provided in the first request.

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree?searchScope=wholeSubtree&ldapFilter=objectClass%20eq%20%22person%22%20and%20sn%20eq%20%22Jones%22"
    }
  },
  "size": 1,
  "_embedded": {
    "entries": [
      {
        "_dn": "uid=lindajones,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/uid=lindajones,ou=people,dc=example,dc=com"
          }
        }
      }
    ]
  }
}

For more information about filtering, see Filtering collections.

Search using POST

You can also search using a POST /directory/v1/{dn}/subtree/search request to avoid placing confidential information in the request URI. Any parameters that are typically placed in the query string are passed in as a JSON object in the request body. The self and next links in the response have data attributes that contain the request body associated with the link.

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"
}'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree/search",
      "data": {
        "filter": "objectClass eq \"person\" and sn eq \"Jones\"",
        "searchScope": "wholeSubtree",
        "limit": 20,
        "includeAttributes": "*,_operationalAttributes",
        "excludeAttributes": "sn,isMemberOf"
      }
    }
  },
  "size": 1,
  "_embedded": {
    "entries": [
      {
        "_dn": "uid=lindajones,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/uid=lindajones,ou=people,dc=example,dc=com"
          }
        }
      }
    ]
  }
}