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)

```json
{
  "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) |