A REST API Design Checklist You Can Defend in Code Review
Naming, cursor pagination, filtering, versioning, rate limits and standard error bodies, each with the reason behind it, not just the rule.
On this page
Good API design rarely shows up in a demo. It shows up eighteen months later, when a client integrates, a collection hits ten million rows, or someone needs to change a field. Each choice below is about not hurting future you.
1. Name resources, not actions
Use plural nouns and let HTTP methods carry the verb: GET /orders, POST /orders, GET /orders/42, DELETE /orders/42. Keep naming consistent: one casing style, one pluralization rule, collections that look the same everywhere. Predictability is the feature.
Why: a client that has used one endpoint can guess the rest.
2. Paginate everything that can grow
Never return an unbounded list. Two strategies:
Offset (?page=3&limit=50) | Cursor (?after=<token>&limit=50) | |
|---|---|---|
| Simplicity | Very simple | Slightly more work |
| Deep pages | Slow, database scans and skips rows | Fast, seeks from the last item |
| Changing data | Can skip or repeat items | Stable |
| Jump to page N | Yes | No |
Prefer cursors for large or fast-moving data, and offsets for small admin lists. Return the next cursor in the body or in a Link header (RFC 8288) so clients follow links instead of building URLs.
3. Make filtering and sorting visible in the URL
GET /orders?status=paid&sort=-created_at lets people see, share and cache exactly what was asked. Document the allowed fields and defaults, and reject unknown parameters with a clear error rather than silently ignoring typos.
4. Change additively, version deliberately
- Prefer additive changes
Adding a field or an optional parameter does not break existing clients. Renaming or removing does. Default to adding.
- Pick one versioning mechanism
A version in the path (
/v2/orders) is the most visible and the easiest to route and cache. A header is tidier but easier to miss. Whichever you pick, use it everywhere. - Deprecate with dates
Announce the removal date, return a deprecation signal in responses, and keep the old version alive until real usage drops. A policy matters more than the mechanism.
5. Rate limit loudly
Return 429 Too Many Requests with a Retry-After header. Document the limits per key, and consider exposing remaining quota in headers so well-behaved clients can slow down before they are blocked.
Why: clients that get a clear “wait 30 seconds” back off. Clients that get a vague 500 retry immediately and make it worse.
6. Make unsafe retries safe
Networks fail after the server already did the work, so clients retry POST /payments and charge twice. Accept an Idempotency-Key header on non-idempotent operations, store the result for that key, and return the same response on a repeat. This is the pattern payment APIs popularized, and it applies to any create-or-charge endpoint.
7. One error format, everywhere
Use the standard problem details shape from RFC 9457, with application/problem+json:
{
"type": "https://api.example.com/errors/insufficient-funds",
"title": "Insufficient funds",
"status": 422,
"detail": "Balance is 30, but the charge is 50.",
"instance": "/payments/abc123"
}
Pair it with the right status code: 4xx for client mistakes, 5xx for server failures. Add machine-readable fields (an error code, the offending parameter) so clients can branch on them instead of parsing sentences.
8. Secure by default
Require authentication on everything except what you deliberately make public, authorize per resource (not just “is logged in”), use HTTPS only, and never put secrets in URLs, because URLs end up in logs.
Do
Write the policy down (pagination, versioning, errors, limits) in one page and enforce it in review. Consistency across endpoints is worth more than any single clever design.
Don't
Let each endpoint invent its own error shape, pagination style and naming. Every inconsistency becomes a special case in every client forever.
Takeaway
None of this is exotic. It is a short list of decisions that, made once and applied everywhere, turn an API from a collection of endpoints into a product. Name resources, paginate with cursors, change additively, rate limit with signals, make retries safe, and return one error format.
Frequently asked questions
Should I use offset or cursor pagination?
Offset pagination (page and limit) is simple but gets slow on deep pages and can skip or repeat items when rows are inserted during paging. Cursor pagination returns an opaque token pointing at the last item seen, staying fast and stable on changing data. Use cursors for large or fast-changing collections.
What should an API error response look like?
A consistent machine-readable body. RFC 9457 defines a problem details format with fields like type, title, status, detail and instance, served as application/problem+json. Using a standard shape lets clients handle every error uniformly instead of parsing a different format per endpoint.
How should I version a REST API?
Pick one mechanism and stick to it: a version in the URL path is the most visible and cache-friendly, a header is cleaner but easier to miss. More important than the mechanism is the policy: avoid breaking changes, add fields instead of changing them, and announce deprecations with dates.
How do I tell clients they are being rate limited?
Return 429 Too Many Requests with a Retry-After header saying how long to wait. Document your limits, and consider headers that expose the remaining quota, so well-behaved clients can slow down before they hit the wall instead of retrying blindly.



/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.