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
-
GET /directory/v1/{dn}/subtree
List all entries -
POST /directory/v1/{dn}/subtree/search
Search using POST
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"
}
}
}
]
}
}