Jon Chery
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 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) | |