atelier/domains/api/pagination.md

Pagination — Derived Rules

Derives from domains/api/first-principles.md P7 (Performance) and P3 (Predictability).

Three Patterns

1. Offset/Limit (?page=2&limit=20)

• Simple, supports jumping to a page.
• Unstable under inserts: page 2 becomes page 1's content after an insert.
• Slow for large offsets: OFFSET 10000 scans 10000 rows.
• Use for: small, stable collections, admin UIs.

2. Cursor (?cursor=base64token&limit=20)

• Stable under inserts: the cursor points to a position, not a page number.
• Fast: indexed lookup, no scan.
• No random access (cannot jump to page 5).
• Use for: infinite scroll, feeds, large collections, anything user-facing.

3. Keyset (?after_id=123&limit=20)

• Like cursor but uses the actual sort key (e.g., after_id=123).
• Most stable and fast. Requires a unique, monotonic sort key.
• Use for: ordered collections with a natural unique key.

Defaults (P3 Predictability)

• Default limit: 20 or 50. Never unbounded.
• Max limit: 100 or 200. Reject limit=10000 with 400.
• Default sort: by created_at descending, or by the resource's natural order.
• Always return the total count if cheap; never if it requires a separate COUNT query on a large table.

Response Shape (P2 Clarity)

{
  "data": [...],
  "pagination": {
    "cursor": "next-base64-token",
    "has_more": true
  }
}

• cursor is null when there is no next page.
• has_more is the boolean convenience (some clients prefer it).
• Never return data as a bare array — always wrap so you can add pagination without breaking.

Link Header (alternative)

Link: <https://api.example.com/users?cursor=X>; rel="next", <https://api.example.com/users?cursor=Z>; rel="prev"

• Useful for HTTP-level clients (curl, browser fetch).
• Less convenient for JSON-parsing clients.

Consistency (P8 Consistency across endpoints)

• Every collection endpoint paginates the same way.
• A client that learns pagination on /users should know it on /orders.
• Mixed pagination (cursor here, offset there) is a tax on every consumer.

What Violates Pagination

Violation	Principle
Returning 10000 items by default	P7 Performance
limit with no max	P8 Security (DoS)
Page numbers on a frequently-inserted table	P3 Predictability
Bare array response (no pagination wrapper)	P1 Contract Fidelity (can't add pagination later without breaking)