PingOne Platform APIs

Paging, ordering, and filtering collections

Not all management API endpoints support paging, ordering, and filtering of collections data returned by GET requests.

Pagination

PingOne supports cursor-based pagination to return large collections in consumable pages. When an operation supports pagination, the following conventions are used:

  • Page limits

    Page limits are requested using the limit query string. If the limit parameter value is omitted, the operation returns the lesser of the service-defined maximum page size or the number of items in the collection.

    For some requests, supported limits are not always honored. For example, the page size limit of 200 for the /environments/{{envID}}/users endpoint result may be smaller. When determining the number of records returned per page, use the page size in the response rather than the requested limit.

  • Self, next, and previous links

    The response body includes a self link in the _links object. If there are more pages available, the response includes a next link in the _links object. If there are previous pages of results available, the response includes a prev link in the _links object.

    To get the next or previous set of pages, follow the next or prev link, then using the same access token, run another GET request using the the next or prev link as the URL.

  • Multiple pages

    If there is more than one page, the response returns a URL-safe cursor in the cursor query string parameter for the next or prev links.

  • Response metadata

    The response can include the following metadata about the results in the body of the payload:

    • count (optional).

      Describes the number of items in the collection or result set (such as the total item count). If a response does not return a count attribute, this usually means there are many in the result set.

    • size (optional).

      Describes the size of the page of results (such as the limit or service-defined maximum page size).

Here is a sample request that limits the collection returned to a maximum of 2.

GET {{apiPath}}/environments/{{envID}}}/populations?limit=2 HTTP/1.1

Here is the response body.

{
 "_links" : {
  "self" : { "href" : "https://api.pingone.com/v1/environments/{{envID}}/populations?limit=2" },
  "next" : { "href" : "https://api.pingone.com/v1/environments/{{envID}}/populations?cursor=xygdhs&limit=2" }
 },
 "count" : 50,
 "size" : 2,
 "_embedded" : {
  "populations" [
   {
    "name" : "Accounting",
    "id" : "12345-aaa-12345"
   },
   {
    "name" : "Engineering",
    "id" : "12345-aaa-12346"
   }
  ]
 }
}

Ordering collections

The PingOne API supports ordering collection results. The following conventions are used:

  • order query string

    The order query string parameter specifies the attribute used to order the results. To return a collection in descending order, prefix the attribute with a minus sign ("-"). Here is a sample of ordering on the name attribute in descending order:

    https://api.pingone.com/v1/environments/{{envID}}/variables?filter=name%20co%20%22r%22&order=-name

  • Multiple column ordering

    An operation can support ordering multiple columns in the order parameter by separating the columns with a comma. If an operation supports multiple columns, it treats the comma as a "THEN BY" directive. For example, order=dateTime,name indicates that the collection is sorted by dateTime then by name.

Filtering collections

Requests that return a large number of items can be filtered using the filter query string parameter. The PingOne platform supports the SCIM protocol filtering operators listed in the following table. However, a particular operation may not support all SCIM filtering operators. If a filtering operator is not supported, the operation returns 400 REQUEST_FAILED code in the response. The details section of the message returns an INVALID_FILTER code as the cause of the error.

Operator Description Behavior

eq

equal

The attribute and operator values are identical.

ne

not equal

The attribute and operator values must not 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.

gt

greater than

If the attribute value is greater than 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.

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.

lt

less than

If the attribute value is less than 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 example, here is a sample SCIM filtering expression that returns users with a last name of "Smith" and a phone number that starts with the "512" area code:

https://api.pingone.com/v1/environments/{{envID}}/users?filter=name.family eq "Smith" and mobilePhone sw "512"

Here is the same filter with URL-encoding to account for spaces (%20) and quotation marks (%22):

https://api.pingone.com/v1/environments/{{envID}}/users?filter=name.family%20eq%20%22Smith%22%20and%20mobilePhone%20sw%20%22512%22

For more information about the SCIM Protocol Specification, refer to "Section 3.4.2.2. Filtering," in the SCIM Protocol Specification.