textANYrestconsistencyresponses
text
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.
REST API Best Practices and Anti-Patterns
High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Best practices
Design choices that improve consistency and developer experience.
httpANYrestobservabilityrequest-id
http
X-Request-Id: req_01HXYZ123A request identifier lets support teams correlate API failures with logs and traces quickly.
textANYresttimestampsiso8601
text
2026-03-27T22:15:00ZISO 8601 timestamps are broadly interoperable and less ambiguous than locale-formatted date strings.
httpANYrestrate-limitsheaders
http
RateLimit-Limit: 100
RateLimit-Remaining: 24
RateLimit-Reset: 60Returning limit metadata helps clients self-throttle and debug rate-limit behavior.
bashANYrestdocscurl
bash
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.
Anti-patterns
Common API design mistakes that age poorly.
textANYrestanti-patternroutes
text
Avoid: POST /createUser
Prefer: POST /usersUsing verbs in CRUD endpoints usually leads to inconsistent route shapes and redundant semantics.
textANYrestanti-patternstatus-codes
text
Avoid: HTTP 200 with { "success": false } for validation failuresMeaningful status codes help caches, clients, SDKs, observability tools, and humans interpret results correctly.
textANYrestanti-patterndomain-model
text
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.
textANYrestanti-patternversioning
text
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.
textANYrestanti-patternnesting
text
Avoid: /orgs/{orgId}/teams/{teamId}/projects/{projectId}/tickets/{ticketId}/commentsVery deep routes make identity, authorization, and caching rules harder to reason about.
More in REST API
REST API Request and Response Patterns
JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.
REST API Authentication, Authorization, and Versioning
Bearer auth, API keys, permission errors, versioning strategies, and compatibility patterns for HTTP APIs.
REST API Status Codes and Error Response Design
Practical HTTP status codes, error response bodies, validation failures, and troubleshooting-friendly API error contracts.
REST API Pagination, Filtering, Sorting, and Search
Common collection query patterns including offset pagination, cursor pagination, filtering, sorting, and search.
REST API Resource Naming and URL Design
Naming conventions for resources, relationships, nested endpoints, and clean URL design.
REST API Methods and Idempotency
HTTP methods, safe vs unsafe semantics, and idempotency examples for API consumers and designers.