json
{
"name": "Ava Martin",
"email": "ava@example.com",
"role": "admin"
}Notes
A clean top-level object is often enough for private APIs and straightforward CRUD designs.
REST API Request and Response Patterns
JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
JSON request patterns
Shape JSON bodies consistently for creates and updates.
json
{
"timezone": "America/Los_Angeles",
"marketing_opt_in": false
}Notes
Small patch bodies minimize payload size and avoid accidental overwrites.
json
{
"items": [
{ "sku": "sku_1", "qty": 2 },
{ "sku": "sku_2", "qty": 1 }
]
}Notes
Bulk endpoints can reduce chattiness, but they need clear per-item success and failure semantics.
Response shaping
Support flexible reads without proliferating endpoints.
http
GET /users/usr_123?fields=id,name,emailNotes
Sparse fieldsets reduce overfetching for large objects and mobile clients.
Embed related resources on demand
Include relationships when the client asks for them.
httpANYrestincluderelationships
http
GET /orders/ord_123?include=customer,itemsNotes
Optional includes preserve a lightweight base contract while allowing richer reads.
Return an ETag for concurrency and caching
Tag a representation with a revision validator.
httpANYrestetagconcurrency
http
ETag: "686897696a7c876b7e"Notes
ETags can power both conditional caching and optimistic concurrency checks.
Protect updates with If-Match
Prevent lost updates from concurrent writes.
httpANYrestif-matchoptimistic-locking
http
PATCH /documents/doc_123
If-Match: "686897696a7c876b7e"Notes
If the entity tag no longer matches, the API can reject the write and ask the client to refetch.
Represent async work as a job resource
Queue work and let clients poll job state.
jsonANYrestasyncjobs
json
{
"id": "job_123",
"status": "queued",
"url": "/jobs/job_123"
}Notes
This pattern works well when a request takes too long to finish within a normal synchronous response window.
More in REST API
REST API Best Practices and Anti-Patterns
High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.
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.