Paging

Summary

A collection endpoint is one that will return multiple results. When sending requests to one, results will be paged to improve performance, as it is unlikely that all results in a collection are required at the same time.

This guide will explain how this works, the additional metadata that is returned and how to customise the paged results...

Paging Headers

When making requests to a collection endpoint, the API will respond with additional metadata in the HTTP headers, that are sent back with the response. This additional information will aid you when requesting further pages of the data, or save you from sending more requests!

The X-Total-Count header gives you the total number of records in the collection and means that you no longer have to traverse the entire collection. 

Instead of having to hard code the navigation logic for traversing collections, you can use the URLs returned in the Location header. The API will return links for the first, previous, next and last pages where appropriate; so it won't send you a link for the first page if you have just requested it, for example.

An example request to the Employees endpoint and the additional paging headers that are returned:

curl -i "https://api.youmanage.co.uk/Employees"
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Location: <https://api.youmanage.co.uk/Employees?page=2>; rel="next",<https://api.youmanage.co.uk/Employees?page=7>; rel="last",
X-Total-Count: 128

{
    ...
}

To confirm, we have omitted the response data for brevity.

Paging Options

You can configure how many results are returned on each page of a collection endpoint, by using the PageSize request variable. This can help reduce the number of calls made to the API if you are expecting a lot of results and conversely, can save data by only requesting the exact number of results you need.

You can select a page size in the range of 5 to 50 results per page. However, if you supply a value outwith that range the API will limit it to the closest boundary without warning. For example, if you send a PageSize of 75, the API will limit that to 50 results per page:

curl -i "https://api.youmanage.co.uk/Employees?PageSize=6"
HTTP/1.1 200 OK
Location: <https://localhost:44336/Employees?PageSize=6&page=1>; rel="next",<https://localhost:44336/Employees?PageSize=6&page=3>; rel="last"
X-Total-Count: 22
Date: Fri, 16 Aug 2019 13:03:48 GMT

[
    ...
]

Next up we'll look at the structure of error messages from the API and how to interpret them.