Pagination

Walk an entire collection with a cursor, and keep the walk correct while the catalogue changes underneath it.

Read every record a collection holds by following a single field. Each response carries a page under data and, while more remains, a cursor under next.

Walk a collection

Send the next value back as cursor:

curl 'https://api.gymassets.dev/v1/equipment' \
-H "Authorization: Bearer $GA_SECRET_KEY"

curl 'https://api.gymassets.dev/v1/equipment?cursor=<the next value>' \
-H "Authorization: Bearer $GA_SECRET_KEY"

next is absent on the final page. Stop when it is missing rather than requesting again for an empty array.

Keep every filter on every request of a walk. A cursor continues the query it was issued for. Dropping a filter part-way through walks a different set.

Treat the cursor as opaque

The cursor’s format is not part of the contract. Send it back exactly as it arrived and read nothing out of it.

The catalogue may change mid-walk. A record added or retired between one page and the next will not cause a row to be skipped or returned twice.

A cursor that did not come from a next field is refused rather than treated as the start of the collection:

{
  "error": "bad_cursor",
  "detail": "Cursors come from the \"next\" field of a previous page."
}

Page size is fixed

Every collection returns a page of the same size, and no parameter changes it. limit, per_page, perPage, page_size, pageSize, count, offset, and page are refused rather than ignored:

{
  "error": "page_size_not_negotiable",
  "parameter": "limit",
  "detail": "Every collection returns 10 records. Follow the cursor in \"next\" for more."
}

A refusal names the parameter it rejected in parameter.