Bitium

Languages

Getting Started - Pagination

For responses that retrieve multiple objects, there are two optional URL query parameters that control pagination:

Name Required Description
per_page No Maximum items to show on each page
Default: 20
Max: 100
page No The page number for items at indices from per_page * (page - 1) to per_page * page
Default: 1
Min: 1

Headers for Paginated Responses

Pagination occurs in the headers, not in the response body. By default, paginated endpoints will return 20 results per page. Pagination syntax follows RFC 5988 standards.

Pagination-eligible responses will have link, total, and per-page properties which are relevant to pagination.

Name Description
link URIs for sequential pages. Only exists if additional links exist (ie, total < per-page)
per-page Allowable items per page
Default: 20
Max: 100
total Total retrievable items

Parsing the `link` property

The link property will only appear if there is more than one page of data. The syntax for links is

<{url}>; rel="{relation}",

Which can be parsed using this regular expression:

<([^>]+)>; rel="(first|prev|last|next)",?

The regex will return up to four matches, each with two match groups.

  • Group 0: the URI for the related page
  • Group 1: relation type (first, prev, next, or last)

There are four types of relations:

Name Description
first The start of the list
Does not appear if the first page was retrieved, or if only one page of results exist.
per-page The tail end of the list, which contains total mod per-page items
Does not appear if the last page was retrieved, or if only one page of results exist.
prev The previous per-page items
Does not appear if first page was retrieved, or if only one page of results exist
next The next per-page items
Does not appear if last page was retrieved, or if only one page of results exist

Sample URL with Pagination

GET https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?per_page=10&page=3

Sample Response Header

cache-control private,max-age=0,must-revalidate
connection keep-alive
content-encoding gzip
content-length application/json
date Thu, 27 Aug 2015 16:17:36 GMT
etag W/"e141ea4fb45bbab35e9b6aa04d614ad6"
link <https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=1&per_page=10>; rel="first",
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=2&per_page=10>; rel="prev",
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=5&per_page=10>; rel="last",
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=4&per_page=10>; rel="next"
per-page 10
server nginx
status 200 OK
strict-transport-security max-age=31536000
total 46
x-request-id 225a675e-4c52-420f-a368-4e9b30df73fb
x-robots-tag noindex
x-runtime 0.222935
x-token-expires-in 315359620

Sample `link` property

<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=1&per_page=10>; rel="first"
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=2&per_page=10>; rel="prev"
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=5&per_page=10>; rel="last"
<https://www.bitium.com/api/v2/organizations/3775/admin/directories/696/users?page=4&per_page=10>; rel="next"