Loyalty APIs are moving from pagination towards cursors. Here how it works.
Cursor system
There are three query parameters you can set:
Cursor list
This list is not paginated, you will need to use
cursor
to navigate it. Therefore modifying the navigation parameters (being the sorting conditions), will change the cursors associated (meaning you can't use a cursor from one sorting by on another sorting by).
This is a common system to efficiently scroll list and allow incremental data fetching by external systems so they can be certain to be up to date.
Unlike paginated lists, the response time of the APIs will remain stable from one call to another.
How to use cursors
There are three query parameters that you can set:
limit
: The number of elements returned (between 0 & 1000)before
: The cursor representing the first element of the current sublistafter
: The cursor representing the last element of the current sublist
Cursor by default
If you don’t add the cursor in the query, the default cursor will be added : limit=50 & order par ID (descending order)
// Here the part of a API response concerning cursors
// http://api.com/loyalty/points?limit=10
{
"paging":{
"cursors":{
"after":"WzExNiwiMTAwMzc1NTg0NDcyMCJd",
"before":null
},
"previous":"https://api.com/loyalty/points?limit=1",
"next":"https://api.com/loyalty/points?limit=1&after=WzExNiwiMTAwMzc1NTg0NDcyMCJd"
}
// All the infos about points instances
...
}
// You can then fetch the next 10 reward attributions by using the cursors, with “after”
// http://api.com/loyalty/points?limit=10&after=WzQzLCIxMDAyNDc3NTI0MjU1Il0=
You can also use the “previous” or “next” that are conveniently created for you not even to have to create the URL manually.
By using this method you can iterate through all of the reward attributions until the API responds with an "after" set to "null".
{
"paging":{
"cursors":{
"after": null,
"before":"WzUyLCIxMDAzMDc4NDIzODU1Il0="
}
}
// All the infos about points instances
...
}
List boundaries
A null “after” cursor means that you have reached the end of the list!
A null “before” cursor means that you have reached the beginning of the list!On both of these cases, there’s no more information to fetch.
Filtering
If you’re looking for a specific element of the list there’s a way to filter to fetch only elements that respect a specific condition.
How to filter
You have to use query parameters that always follow the same pattern:
?the_name_of_the_property={"operator": XX, "value": YY}
Operator | Operator definition | Date property | String property | Number property |
---|---|---|---|---|
equals | X | X | X | |
not equals | X | X | X | |
gte | Greater Than or Equals | X | X | |
gt | Greater Than | X | X | |
lte | Less Than or Equals | X | X | |
lt | Less Than | X | X | |
on date | X | |||
contains | X | |||
not contains | X | |||
begins | X | |||
ends | X | |||
is empty | X | |||
is not empty | X |
Values you can use
There’s no limitation for values, just use values that make sense with what you are looking for.
And respects the YYYY-MM-DD HH:MM:SS
format for date time and YYYY-MM-DD
for the date.
You can add multiple conditions at the same time: ?property1=...&property2=...
Examples
Fetch the points that are given to people in the gold tier and that have a validity end greater than 2022-06-20 00:00:00
https://api.com/loyalty/points?tier_name={"operator":"equals", "value": "gold"}&validity_end={"operator":"gt", "value": "2022-06-20 00:00:00"}
Fetch only the points of a specific card code 0981271872
https://api.com/loyalty/points?card_code={"operator":"equals", "value": "0981271872"}
Fetch the rewards attribution of a member that can be burnt. In this case, we want the list of rewards with a valid
status on a specific user (and not expired or pending).
https://api.splio.com/loyalty/v2/contacts/{id}/rewards?limit=50'&status={"operator":"equals", "value": "valid"}
Sorting
Depending on which order you would like to see the elements of the list you can choose ascending or descending.
How to sort
There are query parameters that you can set:
order
: Use ‘asc' for ascending or ‘desc’ for descending
Note that the cursors
values are linked to the sorting_by
.
Available only for Loyalty points:
sorting_by
: By default elements are sorted using internal ID so they appear one after the other depending on when they were added in Splio. But some APIs allow you to choose how the elements are sorted. For example, Loyalty points API allows ID
(the one by default) but also EventDate
to sort by date at which the points were credited.
Example
https://api.com/points/program/1?sorting_by=EventDate&order=desc
Remember that you can use all these mechanisms at the same time
https://api.com/rewards/186/attributions?limit=1000&order=desc&expiration_date={"value": "2022-10-11 00:00:00", "operator": "gte"}
Error cases
Invalid cursor (400)
Specifying an invalid “before” or “after” value for cursor will result in a 400
{
"error_key": "cursor",
"error": "invalid_cursor",
"error_description": "Paginate: invalid cursor for paginating"
}