REST API – Support filtering and specifying the attributes to retrieve in the same request

Introduction

This short document is considered as a user guideline on how to use the filtering endpoint along with specific attributes to retrieve only needed information instead of receiving the whole resource information.

SCIM 2.0 specification

In the SCIM 2.0 specification there is an attributes parameter that can be used to only retrieve specific attributes:

In addition to filtering the response it is also possible to ask the service provider to sort the Resources in the response, return specific attributes of the resources, and return only a subset of the resources.

https://example.com/{resource}?filter={attribute} {op} {value} & sortBy={attributeName}&sortOrder={ascending|descending}&attributes={attributes}

https://example.com/Users?filter=title pr and userType eq “Employee”&sortBy=title&sortOrder=ascending&attributes=title,username

Supported endpoints

From 5.6 version, Identify REST API supports filtering endpoint’s “attributes” parameter for all resource endpoints including:

  • api/rest/v2/users/.filter

  • api/rest/v2/claimdefinitions/.filter

  • api/rest/v2/connections/.filter

  • api/rest/v2/groups/.filter

  • api/rest/v2/organizations/.filter

  • api/rest/v2/attributeservices/.filter

  • api/rest/v2/transformations/.filter

  • api/rest/v2/messagequeues/.filter

Response Info and Examples

This parameter is an optional one, so if it is not presented, the whole resource information is returned.

Example:

admin/api/rest/v2/users/.filter?filter=displayName%20co%20%22admin%22&sortBy=displayName&sortOrder=Ascending

This request will return a list of users with full information:

image1

With the support of “attributes” parameter, we can specify to return a subset of user information, “userName,displayName,email” for example:

admin/api/rest/v2/users/.filter?filter=displayName%20co%20%22admin%22&sortBy=displayName&sortOrder=Ascending&attributes=userName%2CdisplayName%2Cemails

Now, only required fields information is returned

image2

Note:

  • “Id” is a required field, so it is returned by default even if it is not included in the “attributes” parameter.

  • Identify REST API attributes filter only supports the first level of resource’s attributes.

  • A nonexistent attribute will be ignored by default.