Paginating Results
Pagination in the API is handled via the Link header standard:
curl -i https://api.attlaz.com/0/projects/1/groups/
HTTP/1.0 200 OK
Date: Sat, 14 Feb 2015 18:47:20 GMT
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS
Link: <https://api.attlaz.com/0/projects/1/groups/?&cursor=1420837590:0:1>;
rel="previous"; results="false",
<https://api.attlaz.com/0/projects/1/groups/?&cursor=1420837533:0:0>;
rel="next"; results="true"
When supported, cursors will always be returned for both a previous and a next page, even if there are no results on these pages. This allows you to make a query against the API for yet-undiscovered results. An example where this would be used is when you’re implementing polling behavior and you want to see if there is any new data. We return a results="[true|false]"
indicator to determine if you actually need to paginate.
Pagination Example
Here is a pagination example using this API endpoint:
https://docs.api.attlaz.com/events/list-an-issues-events/
The HTTP request in this example returns 100 events for the issue and has the following link header in the response:
<https://api.attlaz.com/0/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="false"; cursor="0:0:1", <https://api.attlaz.com/0/issues/123456/events/?&cursor=0:100:0>; rel="next"; results="true"; cursor="0:100:0"
One of the URLs in the link response has rel=next
, which indicates the next results page. It also has results=true
, which means that there are more results.
Based on this, the next request is GET <https://api.attlaz.com/0/issues/123456/events/?&cursor=0:100:0>
.
This request will return the next 100 events for that issue, again, with the following link header:
<https://api.attlaz.com/0/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="true"; cursor="0:0:1", <https://api.attlaz.com/0/issues/123456/events/?&cursor=0:200:0>; rel="next"; results="true"; cursor="0:200:0"
The process is repeated until the URL with rel=next
has the flag results=false
to indicate the last page.
The three values from cursor are: cursor identifier (integer, usually 0), row offset, and is_prev (1 or 0).