# Pagination

## Overview
Lists of objects are returned as a flat list - that is, the objects are not wrapped in a container in the HTTP response. 
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 [Blueink API client libraries](/docs/libraries/) include convenience methods to work with paged results.