Pagination
Overview
StackOne’s allows paginating the API requests. Pagination is a modern way to fetch the data in bulk. Iterating through thousands of data pages can be done using the advanced optional next
parameter.
It is often called cursor pagination.
Mechanism
The legacy approach of StackOne API was to pass page
parameter to identify which page of data has to be returned in response. Now, when making the first API request and if the response contains over 25 records, you will get next
value of a string type. This property can be passed as a query string parameter for subsequent requests until the next
value becomes NULL.
Sample scenario
For example, you want to list all employees for the BambooHR integration. You have around 525 employees configured. In such a case, StackOne returns the next
parameter string value on the first request. Then, you can iteratively get the new value of next
parameter to get all the remaining employee records.
Sample response
In the response payload, you can find the next
cursor.
Once the cursor reaches the end of the data list, both values become NULL.
Page Size
By default, the page_size
parameter is set to 25 results per page, you can over-ride this by passing in a custom page size with this parameter. If fewer records remain in the underlying connected provider than a given page_size, you will not receive a next
cursor value on the next request.
For example, if you have 17 records in total, all of them will be shown on one page with next
parameter being empty. Then you specify the page_size
= 10, you’ll get the next
value. If you use this next
value, you will get a stripped array of the last 7 records.
Early Cursor return
Occasionally we have to apply custom filters or structure requests to ensure we can get data which is not returned by the native API, this can cause timeout issues where we wouldn’t fill an entire page.
In this case we will return a cursor value with the incomplete page, and you can continue paginating through the data to the end of the data set. When the final record is reached on the underlying provider we will return an empty next cursor.