API Pagination

When to use

• The user needs to expose next/previous page navigation and page-size limits in an API response.
• The user must choose between offset/limit and cursor-based pagination for an API collection.
• The user needs to return a large collection from an API in pages rather than all at once.

When NOT to use

• Do not page a full bulk export where the client wants every row; stream the response or provide an async export job instead.
• Do not paginate a collection that is inherently small and bounded, such as a fixed list of a user's roles or a handful of settings.

Core guidance

• Prefer cursor pagination for deep or fast-changing data — Use cursor (keyset) pagination — a cursor pointing at the last seen sort key — for large, deep, or frequently changing collections. Reserve offset/limit for small datasets or when clients need to jump to an arbitrary page number.
• Enforce a default and maximum page size — Apply a sensible default page size (for example 20) and clamp the client-supplied size to a hard maximum (for example 100). Reject or cap oversized requests rather than honoring an unbounded per_page.

Quick recipe

1. Choose a stable, unique, indexed sort key (for example id or created_at, id), read the requested page size, and clamp it to the server maximum. (verify: The chosen key is indexed and unique, and an oversized page-size request is capped.)
2. Decode the incoming cursor to the last seen key value and query WHERE (sort_key) > :cursor ORDER BY sort_key LIMIT :size + 1, fetching one extra row to detect whether more pages exist. (verify: The query seeks by the indexed key and the extra row correctly indicates has_more.)
3. Return the page items plus a consistent meta block — the next cursor (encoded from the last item), a has_more flag, and a ready-to-follow next link. (verify: Following the returned next link fetches the subsequent page with no gaps or duplicates.)

Best practices

• Do not compute an exact total count on every page request
• Include ready-to-follow next (and prev/first where meaningful) links or the next cursor in the response, so clients follow links rather than constructing page URLs themselves
• Order pages by a stable, unique key (or a composite ending in the primary key) that is indexed, and derive the cursor from it

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Deep offsets get progressively slower — A query like LIMIT 20 OFFSET 100000 still scans and discards the first 100000 rows before returning the page. Fix: Switch deep pagination to keyset/cursor so each page seeks directly to the next range via an index.
2. Offset pagination skips or repeats rows under writes — With offset/limit, a row inserted or deleted between page requests shifts the window, so clients skip or see duplicate items. Fix: Use cursor (keyset) pagination anchored on a stable key so the next page continues from the last seen item regardless of inserts.
3. Honoring an unbounded client page size — Trusting the client's per_page without a cap lets ?per_page=1000000 pull the whole table in one response. Fix: Clamp the requested size to a hard maximum server-side and document the ceiling.

Version notes

• The Link header format is standardized by RFC 8288 (PHP >=8.1) — When returning pagination links in the HTTP Link header, use the RFC 8288 web linking format with rel="next" and rel="prev"; the same relations also work inside a JSON links block.

Security

• Keep cursors opaque and scoped to the caller — Validate the decoded cursor as untrusted input and re-apply the caller's authorization filter (tenant, owner) to every page, so a forged or swapped cursor cannot page into another user's records or crash the decoder.

Testing

• Activation and decision behavior are verified in eval/scenarios/api/pagination.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: api/openapi, api/rest-design, security/sql-injection-prevention