Pagination

Overview

Lists of objects are returned as a flat list - that is, the objects are not wrapped in a container. For example, if you retrieve a list of Bundles, the response content will consist of:

[
    {
        ... First Bundle object ...
    },
    {
        ... Second Bundle object ...
    }
]

Example Responses

Most requests for a list of resources are paginated, typically returning 50 results per page. Pagination is implemented via a Link header. For example:

Link: <https://api.blueink.com/api/v2/bundles?search=Bob&page=5>; rel="next",
  <https://api.blueink.com/api/v2/bundles?search=Bob&page=11>; rel="last",
  <https://api.blueink.com/api/v2/bundles?search=Bob&page=1>; rel="first",
  <https://api.blueink.com/api/v2/bundles?search=Bob&page=3>; rel="prev"

Your client should use the URLs returned in the Link header to navigate through pages of results. However, while not recommended, paginated URLs can be constructed manually. Page numbers are 1-indexed (starting at 1, not 0). The pagination parameter in the querystring is 'page'. Many API endpoints also take a 'per_page' parameter that lets a client control how many results are returned per page. The maximum allowed value of per_page is typically 100.

For example:

https://api.blueink.com/api/v2/bundles?search=Bob&page=3&per_page=20

To make working with pagination easier, API responses with paginated results also include a custom HTTP header: X-BlueInk-Pagination. The format of this header value is like so:

X-BlueInk-Pagination: <current page number>,<total pages count>,<results per page>,<total results count>

For example, if the response was for page 2 out of 4, with 50 results per page and 176 total results, the header would be as follows.

X-BlueInk-Pagination: 2,4,50,176

All reference client libraries include convenience methods to work with paged results.