Pagination

In its responses, the API returns up to and including 20 results per request. For requests that result in less than 20 results, you'll get everything you need in one request. However, when you are dealing with a long list of objects, such as a long list of DataPoints on a Device, you may have to process multiple pages.

Shown to the right is an example response to requesting all of the DataPoints on Device 1. The X-Pagination details are provided in the header, in which it lists the total count of objects on this device:

X-Pagination-Total-Count: 35

Additionally, it also provides a total page count and the current page:

X-Pagination-Page-Count: 2
X-Pagination-Current-Page: 1

Finally, the Link header provides references to the current page, the next and/or previous page (when applicable), and the last page in this sequence.

Utilising any of these three pagination descriptions will help you to ensure that all objects are retrieved for any given request.

Headers

Date: Wed, 08 Jun 2016 23:47:39 GMT
Server: Apache/2.2.31 (Amazon)
X-Powered-By: PHP/7.0.6
X-Pagination-Total-Count: 35
X-Pagination-Page-Count: 2
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <https://nexcloud.io/v1.0/Device/1/DataPoint?access_token=123&page=1>; rel=self, 
      <https://nexcloud.io/v1.0/Device/1/DataPoint?access_token=123&page=2>; rel=next, 
      <https://nexcloud.io/v1.0/Device/1/DataPoint?access_token=123&page=2>; rel=last
Content-Length: 5984
Connection: close
Content-Type: application/json; charset=UTF-8

By parsing the pagination headers and including the page parameter in your requests, you'll ensure that you always get all of the objects for any request.

One easy way would be to start with &page=1, and continue incrementing the page number until the number is equal to the total page count. Pseudo-code for such a traversal can be seen on the right - make sure to properly integrate and test such code before using it.

Query Parameters

// "&page=1" can be added to any request without modifying the result, 
//     as the first page is always returned unless otherwise specified.

int page = 1;
bool lastPage = false;
String myAccessToken = "123";
String url = "https://nexcloud.io/v1.0/Device/1/DataPoint" 
           + "?access_token=" + myAccessToken ;

while (!lastPage)
{
     HTTP response = HTTP.get(url + "&page=" + page);
     // Process the response's body here...

     // Now check if this was the last page.
     if (page == response.getHeader("X-Pagination-Page-Count"))
     {
           lastPage = true;
     }
     
     page = page + 1;
}