Pagination


Results from the API which return collections of objects are paginated, ie. split up into pages. We use a system which is compliant with the proposed RFC-5988 standard for web linking. Paginated responses will return Link and Total HTTP headers. Here is an example:

$ curl https://api.breathehr.com/v1/employees?page=2 -i \
-H 'X-Api-Key: prod-1OcTwKW8ln5ARz04IjsrJEQTZgP3Ir1sWfyuOLdqC1Y’
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.breathehr.com/v1/employees?page=1>; rel="first",
  <https://api.breathehr.com/v1/employees?page=1>; rel="prev",
  <https://api.breathehr.com/v1/employees?page=23>; rel="last",
  <https://api.breathehr.com/v1/employees?page=3>; rel="next"
Total: 572

The Link header contains the URLs for the first, previous, next and last pages of the collection being returned. The Total header contains the total number of records in the collection, not the total number of pages. (The total number of pages is found in the URL for the last page.) These headers can help simplify your client code. As you may have noticed, we tell the API which page to return with a page query parameter. Similarly, we can request more items per page with a per_page parameter, up to a maximum of 100. The default is 25 records per page.'