High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.
Design choices that improve consistency and developer experience.
Use the same top-level response structure across endpoints.
List endpoints should return a predictable structure for data, pagination, and errors.Consistency lowers cognitive load and makes SDKs, docs, and client code easier to maintain.
X-Request-Id: req_01HXYZ123A request identifier lets support teams correlate API failures with logs and traces quickly.
Prefer explicit timezone-aware datetime strings.
2026-03-27T22:15:00ZISO 8601 timestamps are broadly interoperable and less ambiguous than locale-formatted date strings.
RateLimit-Limit: 100
RateLimit-Remaining: 24
RateLimit-Reset: 60Returning limit metadata helps clients self-throttle and debug rate-limit behavior.
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer $TOKEN"Concrete examples reduce onboarding friction and improve the usefulness of documentation and cheat sheets.
Common API design mistakes that age poorly.
Avoid route names that duplicate the HTTP method.
Avoid: POST /createUser
Prefer: POST /usersUsing verbs in CRUD endpoints usually leads to inconsistent route shapes and redundant semantics.
Use HTTP status codes meaningfully.
Avoid: HTTP 200 with { "success": false } for validation failuresMeaningful status codes help caches, clients, SDKs, observability tools, and humans interpret results correctly.
Keep API models stable and intentional.
Avoid exposing internal table names, join tables, and migration-driven field names directly.An API contract should reflect domain concepts, not your current storage layout.
Version or phase in incompatible changes.
Avoid removing fields or changing meanings without deprecation and migration guidance.Silent breaking changes erode trust and create hard-to-debug production failures for clients.
Avoid: /orgs/{orgId}/teams/{teamId}/projects/{projectId}/tickets/{ticketId}/commentsVery deep routes make identity, authorization, and caching rules harder to reason about.