Pagination

The PocketSmith API leverages pagination for collections that are likely to be large in size, such as transactions. This means that it's not possible to request the whole collection at once, you must instead ask the API for a certain page of results. This article explains how the API implements pagination, and how you can use it to load more results in your application.

Response headers

You can identify if a collection is being paginated by the presence of the following headers:

Per-Page: how many results from the collection are on each page (e.g. 30)
Total: how many total records there are across all pages (e.g. 432)
Link: an RFC 5988-compliant header with links to get to the first, last, next and previous pages.

Navigating pages

By default, you will be delivered the first page (page 1) of results. You can request specific pages using the page URL parameter, for example transactions?page=3.

It is recommended to leverage the Link header when navigating between pages. The header will look like:

Link: <https://api.pocketsmith.com/v2/users/18609/transactions?end_date=2015-06-01&page=1&start_date=2011-01-01>; rel="first", <https://api.pocketsmith.com/v2/users/18609/transactions?end_date=2015-06-01&page=12&start_date=2011-01-01>; rel="last", <https://api.pocketsmith.com/v2/users/18609/transactions?end_date=2015-06-01&page=11&start_date=2011-01-01>; rel="next", <https://api.pocketsmith.com/v2/users/18609/transactions?end_date=2015-06-01&page=9&start_date=2011-01-01>; rel="prev"

There are plenty of libraries available across languages which can parse compliant Link headers into a data structure, so definitely look at those before trying to split the string up. Some examples:

parse-link-header for JavaScript
link_header for Ruby
link-rel-parser-php for PHP

Unless the total size of the collection fits exactly into pages of size n, the last page will have less results than the others.

Adjusting the page size

The default number of records per page is 30, but you can change this as needed. You can make the page size as small as 10, or as large as 1000. You just need to specify per_page as a query parameter for the paginated resource, for example transactions?page=3&per_page=500.