Pagination

What is cursor-based pagination

Cursor-based pagination is used for list calls in the REST endpoints that return a large number of items. Where traditional offset-based pagination separates a large list into chunks of x items based upon a possible changing offset, cursor-based pagination uses fixed cursors.

Using a fixed cursor eliminates the possibility of skipping items and supplying the same item in more than one page. It also allows us to cache the response if needed.

For cursor-based pagination, you supply a cursor to use as a start position, and you describe the number of items you want to fetch before or after that cursor, using combinations of the filter parameters: first, after, last, before.

Paginating forward

  • ?first=10 → returns the first 10 results of the complete result set

  • ?first=10&after=c4f87059-0ccb-48ed-9080-3949b075eaa1 → returns the first 10 results after the result with cursor c4f87059-0ccb-48ed-9080-3949b075eaa1 in the complete result set

  • etc.

Paginating backwards

  • ?last=10 → returns the last 10 results of the complete result set

  • ?last10&before=c4f87059-0ccb-48ed-9080-3949b075eaa1 → returns the last 10 results before the result with cursor c4f87059-0ccb-48ed-9080-3949b075eaa1 in the complete result set

  • etc.

When you have fetched one slice of the results and want to fetch the next or previous slice, you will need a cursor, as explained above. Therefore these are returned in the result set, along with booleans that indicate if there is a previous or next page to be fetched. You can find this in the pageInfo node, in the response.

  • When you want to fetch the previous page, you must set the before-filter to pageInfo.startCursor of the current response

  • When you want to fetch the next page, you must set the after-filter to pageInfo.endCursor of the current response.

Example using the pledges endpoint

  1. First day: retrieve until pageInfo.hasNextPage is false in the response, and afterwards store the date and time of now, to be the releasedAfter-value for tomorrow.

    • first page: /api/v1/pledges?releasedAfter=[initial]&first=50

    • second page: /api/v1/pledges?releasedAfter=[initial]&first=10&after=41222ef7-a861-4bbd-ae93-2f645336b85d

    • ...

    • last page: /api/v1/pledges?releasedAfter=[initial]&first=10&after=10d303b1-4eca-4db4-9ae7-7cd65f98a5b5

  2. Second day: retrieve all released after the previous datetime you fetched, retrieve until pageInfo.hasNextPage is false in the response, and afterwards store the date and time of the last pledge you received.

    • first page: /api/v1/pledges?releasedAfter=[previousDay]&first=50

    • second page: /api/v1/pledges?releasedAfter=[previousDay]&first=10&after=bd82f150-a797-4d9f-af09-c3ea06964e9d

    • ...

    • last page: /api/v1/pledges?releasedAfter=[previousDay]&first=10&after=3c53b11a-adef-4dc1-90d7-c23dc0108492

  3. etc.

Last updated