To manage load on the API, various GET endpoints are paging. We generally do this in cases where the item type in question typically has a lot of items, as is the case (for example) with machines, nodes and people.

Page Request

For paging endpoints, request a page using the following HTTP request parameters:

Param Description Default Value
page Page index (0-indexed). 0
size Page size. Maximum value is 500. 100
sort Sort directives. See the examples below for the formats. None. If sort isn't specified, the results aren't sorted.

Examples

Single sort key, default sort direction (asc):

/v1/people?page=3&size=200&sort=username

Single sort key, descending sort:

/v1/people?page=3&size=200&sort=username,desc

Multiple sort keys, same sort direction:

/v1/people?page=3&size=200&sort=lastName,firstName,username,asc

Multiple sort keys, different sort directions:

/v1/people?page=3&size=200&sort=lastName,asc&sort=firstName,desc

Page Response

The API communicates page metadata in the HTTP response headers. The API supports the standard Link header. We also provide a set of extension headers to make it easier for clients to get at the URIs without having to parse Link.

Header Description
Link Standard HTTP header for presenting relevant links.
X-Pagination-First URI for the first page
X-Pagination-Prev URI for the previous page
X-Pagination-Next URI for the next page
X-Pagination-Last URI for the last page
X-Pagination-TotalElements Total number of elements in the result set
X-Pagination-TotalPages Total number of pages in the result set

Examples

Request:

https://seiso.example.com/v1/people?page=2&size=50

Response:

Link: <https://seiso.example.com/v1/people>;rel="self",<https://seiso.example.com/v1/people?view=default&page=0&size=50>;rel="first",<https://seiso.example.com/v1/people?view=default&page=1&size=50>;rel="prev",<https://seiso.example.com/v1/people?view=default&page=3&size=50>;rel="next",<https://seiso.example.com/v1/people?view=default&page=38&size=50>;rel="last"
X-Pagination-First: https://seiso.example.com/v1/people?view=default&page=0&size=50
X-Pagination-Prev: https://seiso.example.com/v1/people?view=default&page=1&size=50
X-Pagination-Next: https://seiso.example.com/v1/people?view=default&page=3&size=50
X-Pagination-Last: https://seiso.example.com/v1/people?view=default&page=38&size=50
X-Pagination-TotalElements: 1904
X-Pagination-TotalPages: 39