Turning a Page: Pagination is Changing

Pagination of EVRYTHNG resources is not as straightforward as we would like it to be. The chief reason for this is that the behavior of pagination varies in small unpredictable ways depending on the type of resource that you are paginating. For example, there are different HTTP headers or query parameters that are not always available. As a result, integrating code needs to be complex, and performance can vary.

We want to improve this, since paginating through many pages of Thngs or products is an activity that will only increase in occurrence as the number of smart products connected to our platform grows. It is also in our interest to make such a widely-applicable API as predictable and usable as possible!

Improving Pagination

Therefore, we are taking some new steps to improve the usability of pagination across the platform. Over the next few months, we will update various resource types to use a single common set of pagination rules. This means that some of the older behaviors will stop working if they are not updated. Some of the most common types already use this pattern, including Thngs, products, actions and properties. Other types, including collections, accounts, applications, batches, files, jobs, places, users and projects, do not, but we hope they soon will.

Another significant change that will occur is the removal of URL encoding inside the Link header in paginated results. This will bring us in line with the specification and improve compatibility. Therefore, new Link header values will look like this:

link: <https://api.evrythng.com/thngs?perPage=30&sortOrder=DESCENDING&nextPageToken=Uk6qwgSReXPat5awagfNpHsk>; rel="next"

Updating Affected Code

These changes have some implications for existing users of paginated resources. While the current pagination behaviors will be staying around for the time being, consumers of the pagination API are strongly recommended to update their code to use the parameters shown in the Pagination documentation page. We have already taken the first step by updating this page to reflect how pagination should ideally be performed from now on. Please take a moment to re-read this documentation and update your code as necessary.

The cut-off date for these changes is June 14th 2017. Please ensure you check and migrate any affected code.

As always, if you have any problems, don’t hesitate to raise a ticket, and we will help you out.