Cursor Pagination

Cursor pagination is the most complex type of pagination, and executing it properly requires setting the correct value in the response mapper.

Cursor pagination works as follows:

1. The initial API request passes an undefined cursor value, which gives you the first set of records.

2. The response then includes the next value to send, which will then give you the next set of records

3. The second (and subsequent) API requests pass the cursor value from the the previous response.

An example flow is as follows:

• Limit = 20, cursor = undefined -> records 0 through 20 (1234 included in the response)

• Limit = 20, cursor = 1234 -> records 20 through 40 (4567 included in the response)

• Limit = 20, cursor = 4567 -> records 40 through 60 (next cursor value included in the response)

• etc.

Within Gravity, this is an automated process so long as it is configured properly in the pagination settings, with the caveat that you need to make sure that meta.cursor is set properly in the response mapper according to the Gravity Standard Response Format.

Extracting the cursor value and setting it in the response mapper

Extracting the cursor value can be complex, and it is important to read the API documentation to understand exactly what the cursor value is, and where it lives. For example:

In this case, you could assume that @odata.nextLink is the cursor value, however the key and value actually live within the URL itself. In this case, cursor pagination is handled with:

Pagination Settings at REST API level:

• Location: Param

• Key: $skiptoken

Response Mapper:

• meta.cursor: Extract $skiptoken from @odata.nextLink , for example:

  if (input.data['@odata.nextLink']) {
      const url = new URL(input.data['@odata.nextLink']);
      const params = new URLSearchParams(url.search);
      result.meta.cursor = params.get('$skiptoken')
  }