Some endpoints may have to return a large data set depending on the query parameters passed to it, to avoid issues that come with returning large data sets, pagination has been put in place.
Query parameters
Query parameters are separated by &.
Conceptually, there are two types of query parameters, filter parameters which are filters specific to the endpoint in question. There are the pagination filters which are parameters passed to URLs solely for pagination purposes.
Pagination filters are the same across all endpoints, unlike filter parameters.
The Customer Reviews API for example has rating, submittedAfter, and submittedBefore as filter parameters.
Of all the reviews stored in the eTrusted Platform for the specified channel, only those that match the filter parameters will be returned to you.
NB: You may end up with an empty list if there are no records matching your query parameter list.
By default, some points are automatically paginated without you initiating them when making a request. In such cases, you will find the paging object added to your response.
You can further control different parts of the response by passing the right query parameter.
For example, if you will like to return say 30 records per request you will have to append &count=30 to the URL of your request.
Also you can get results before or after a specific record by appending &before={id_here} or &after={id_here} respectively.
NB: Should you use the after, or before query parameters, this will not be automatically appended to the next and previous URLs sent back in the paging object.
HATEOAS-based pagination.
The pagination used is based on HATEOAS which means, for every response you get back you will have everything you need to query for the next set of records.
For example, you will find everything regarding pagination in the paging object for navigating to the previous or next list of records.
As shown below:
Cursor object in the response
"paging": {
"count": 10,
"cursor": {
"before": "rev-xxxxxxxa-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
"after": "rev-xxxxxxxb-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
},
"links": {
"previous": "https://api.etrusted.com/channels/{channelId}/customer-reviews?count=10&before=rev-xxxxxxxa-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
"next": "https://api.etrusted.com/channels/{channelId}/customer-reviews?count=10&after=rev-xxxxxxxb-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
}
},
count is the number of reviews displayed on one page of the pagination.
Note that this number might be lower than the count number you passed in your request. This happens when the last page is reached.
For example, A total number of 105 reviews are displayed in chunks of 20 reviews per page.
The sixth and last page will only have 5 reviews.
The count property will hold the value 5.
Note that the links in a real response contain the exact filter parameters that were used in the respective request (rating, submittedBefore, submittedAfter).
This ensures that the pagination is always relative to the same filter in subsequent requests.
FAQ
How do I fetch the latest record?
To fetch the latest record you can use a combination of the submittedAfter and count filters.
How do I skip to a specific page during pagination?
The cursor-based pagination is focused on providing an infinite scroll experience and not so much jumping between pages. However in other to move between different records you can use different filters. For example, you can use submittedAfter to jump between different parts of the record based on when they were created.