Cursor-based pagination

Access paginated data via an opaque token.

Cursor-based pagination allows API consumers to retrieve pages as a linked list.

Pros

Returned results are more consistent, even where the underlying data is frequently modified.
The opaqueness of the cursor makes it resistent to reverse engineering.

Cons

Does not support random access to data.

Usage

Paginated APIs support a query parameters, cursor.

Parameter	Description
`cursor`	An opaque token representing a position in the dataset from which to return results.

Not specifying a cursor returns the first page of results:

Default request

curl https://api.example.com/records

Each response also contains the cursor that can be used to obtain the next page of results:

Example response

{
  "data": [
    {},
    {},
    ...
  ],
  "next_page": "eyJpZCI6MX0"
}

Implementation notes

The cursor represents the last retrieved record, and can be the record's ID, a timestamp for chronologically sorted data, or any other unique trait that can be easily queried.

Regardless of what underlying data the cursor represents, the value should be an opaque encoding such as Base62.

OpenAPI reference

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cursor-Based Pagination Example API",
    "version": "1.0.0"
  },
  "paths": {
    "/records": {
      "get": {
        "summary": "list all records",
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "The starting point from which to return results.",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    }
  }
}