PingOne Platform APIs

Paging and ordering collections

Not all management API endpoints support paging and ordering 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.