Overview

Most API calls return a single entity or a list entity. List entities can contain lots of items and may be paged. It is very important to note that any listing could result in a multi-page response. All clients making such requests must be prepared to handle such a response.

Traversing pages

Pages are traversed by using the <link> tags with the rel attribute next and prev.

Page size

The most common default page size is 1,000. Clients may hint at their preferred page size, by using a query parameter page_size=N. Page sizes are not guaranteed, they may ignored if they are too large, or if the API is under load it might reduce them. If clients wish to present data consistently, it must be prepared to handle a mismatch between the Poppulo API page size and their preferred page size.

Please avoid specifying a page size if the client is going to access all pages sequentially.