How to use cursors lists parameters ?

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 sublist
• after: 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}

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 a “before” or “after” value for cursor that is not valid will result in a 400

{
    "error_key": "cursor",
    "error": "invalid_cursor",
    "error_description": "Paginate: invalid cursor for paginating"
}