Concept
Pagination
Some responses may contain a long list of data. Therefore we limit each request to a standardized amount of 200 objects for a request.
This can be increased or lowered by using the limit query parameter.
While the maximum limit by default is 1000 objects, then some endpoints have different limits.
See the documentation for each endpoint for more info.
GET /api/v1/users?limit=5 HTTP/1.1
Host: api.relesysapp.net
Accept-type: application/json
Authorization: Bearer [Your token]
When the limit query parameter is used, a nextUrl property is returned as part of the result.
This value should be used for automatic pagination.
It will always ensure the next set of results follow the same filters and sorting.
The response for this will contain a nextUrl property.
{
"nextUrl": "https://api.relesysapp.net/api/v1.3/users?limit=5&cursor=e75935bef9584a7398ce0d7b0e84c281",
"data": []
}
If the url requests was done by a nextUrl, then a previousUrl will also be present.
It works the same way as nextUrl, however this time it will give the url to get the previous results.
The nextUrl property will continue to be returned until no more results are available.
{
"nextUrl": "https://api.relesysapp.net/api/v1.3/users?limit=5&cursor=5b62561493f94169895cd4972636f9e2",
"previousUrl": "https://api.relesysapp.net/api/v1.3/users?limit=5&cursor=e75935bef9584a7398ce0d7b0e84c28",
"data": []
}
Cursor (Best practise)
The nextUrl and previousUrl will keep the limit parameter and include a cursor parameter.
This means it won't be possible to jump forward several results, but instead it is required to go from start till end sequentially.
A cursor is used as it ensure the speed is the same whether requesting data on page 1 or page 2000.
Cursors can only be generated by the API and works up to 6 hours after it is first generated. After that they are gone and it will be required to start over. This does not mean a full pagination from start till end has to be done in less than 6 hours. Only that the exact request when a page's cursor is made available, it will last for 6 hours until forgotten.
In some cases it is not possible for the system to provide a cursor, and in those cases offset is used instead. See next section for more info.
The limit can be changed when using a cursor, as the cursor only contains information on where to start getting data from.
Beware that changing the limit during the pagination will make the previousUrl results have a chance of overlaps of data.
Offsets (Manual approach)
While cursors are the most performant, then being able to go to a specific page can be needed.
That is why we also support offset as a parameter. Using offset, means skipping the first n results and then taking the limit results at that point.
An example can be seen below, where we take what is essentially page 2.
GET /api/v1/users?limit=100&offset=100 HTTP/1.1
Host: api.relesysapp.net
Accept-type: application/json
Authorization: Bearer [Your token]
When using offset, the nextUrl and previousUrl will still be generated using cursor if possible.
There can be some cases where the offset parameter is present, but that is only when no other option exists.