REST API Design
REST API design cheat sheet: resource naming, HTTP methods and idempotency, status codes, a request and its response, problem+json errors, offset vs cursor pagination, query conventions, versioning, and a checklist before you ship an endpoint.
Cheat sheet · Offered as a template
In this diagram
- REST API Design
- ① Resources, not actions
- Orders API
- Nouns in the path, verbs in the method. Plural names, lowercase, hyphens.
- ② Methods
- ③ A request and its response
- request
- response
- ④ Status codes
- 2xx · it worked
- 4xx · the client’s fault
- 5xx · the server’s fault
- ⑤ What each stage can answer
- Client
- Authenticate
- 401 · 403
- Rate limit
- 429
- Validate
- 400 · 422
- Handler
- 2xx · 404 · 409
- Response
- JSON
- ⑥ Errors a client can use
- problem+json
- ⑦ Pagination
- Offset: ?page=3&limit=50
- Simple, and you can jump to any page
- Slow and unstable on big, changing lists
- Cursor: ?after=o_123&limit=50
- Stable and fast at any depth
- No jumping to page N
- ⑧ Query conventions
- GET /orders?…
- together
- ⑨ Versioning
- Version in the path (/v1) or in a header: pick one
- Adding a field is not a breaking change
- Removing or renaming one is: new version
- Announce the end of a version with a Sunset header
- ⑩ Before you ship an endpoint
- Authenticated and authorised
- Input validated, sizes capped
- Idempotency key for unsafe retries
- Paginated if it returns a list
- The same error shape everywhere
- Documented in OpenAPI
- Rate limited
- ⑪ Promises worth making
- Availability
- p99 latency
- ⑫ Best practices
- ✓ Be boring: clients guess right when you follow convention