API Design Review
Overview
Judge an API from the client's side: predictable names, honest status codes, one error shape, safe retries, and no surprise breaking changes. Every finding points at a concrete route and shows the corrected design.
Method
- Inventory. List every endpoint as
METHOD /path → status codes → request/response shape. Read routes, controllers, OpenAPI files and DTOs. - Check each endpoint against the rules below.
- Check the API as a whole: consistency across endpoints matters more than any single choice.
- Changes: if reviewing a diff, compare old and new contracts and flag anything that breaks existing clients.
- Report using the contract below.
Rules
| Area | Rule |
|---|---|
| Resources | Plural nouns, no verbs: POST /orders, not /createOrder. Nest only for true ownership: /users/{id}/orders. |
| Methods | GET reads and is safe. POST creates. PUT replaces. PATCH partially updates. DELETE removes. Never change state on GET. |
| Status codes | 200 OK, 201 Created (+ Location), 204 No Content, 400 invalid input, 401 not authenticated, 403 not allowed, 404 missing, 409 conflict, 422 validation, 429 rate limited, 5xx only for server faults. Never 200 with {"error": ...}. |
| Errors | One shape everywhere, e.g. RFC 9457: { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }. No stack traces or SQL in responses. |
| Naming | One casing for JSON fields (camelCase or snake_case), consistent IDs, ISO 8601 UTC timestamps, money as integer minor units or decimal string plus currency. |
| Collections | Paginate every list (cursor preferred for large or changing data), cap page size, return next cursor or links. Filtering and sorting via query params. |
| Idempotency | Retried POSTs that create payments, orders or emails accept an Idempotency-Key. PUT and DELETE are idempotent by design. |
| Versioning | A clear strategy (/v1 path or header). Breaking changes go to a new version. |
| Breaking changes | Removing or renaming fields, changing types, making optional input required, changing status codes or error shape, tightening validation. |
| Security | Auth on every non-public route, object-level ownership checks, rate limits on auth and expensive routes, no sensitive data in URLs. |
| Performance | No unbounded responses, support fields or sparse responses for heavy objects, ETag or Cache-Control for cacheable GETs. |
Output contract
Start with: N endpoints reviewed, M findings (X breaking). Then, highest impact first:
### [Breaking | High | Medium | Low] Title
- Endpoint: METHOD /path (file:line)
- Problem: what a client experiences
- Fix: the corrected route, status code or JSON shape
Finish with a short Consistency summary (casing, error shape, pagination, versioning: consistent or not) and, when designing from scratch, the proposed endpoint table.
Common mistakes
- Reviewing endpoints one by one and missing that two of them disagree on casing or error shape.
- Recommending a redesign when a backward-compatible addition would do.
- Calling a change safe because the server code still works: check what existing clients send and expect.
- Using 500 for validation errors or 404 for permission failures without deciding deliberately.
Made by Wageesha Tripathi · LinkedIn · Email · More skills