jsonANYrestjsoncreate
json
{
"name": "Ava Martin",
"email": "ava@example.com",
"role": "admin"
}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.
jsonANYrestpatchjson
json
{
"timezone": "America/Los_Angeles",
"marketing_opt_in": false
}Small patch bodies minimize payload size and avoid accidental overwrites.
jsonANYrestbulkjson
json
{
"items": [
{ "sku": "sku_1", "qty": 2 },
{ "sku": "sku_2", "qty": 1 }
]
}Bulk endpoints can reduce chattiness, but they need clear per-item success and failure semantics.
Response shaping
Support flexible reads without proliferating endpoints.
httpANYrestfieldsprojection
http
GET /users/usr_123?fields=id,name,emailSparse fieldsets reduce overfetching for large objects and mobile clients.
httpANYrestincluderelationships
http
GET /orders/ord_123?include=customer,itemsOptional includes preserve a lightweight base contract while allowing richer reads.
httpANYrestetagconcurrency
http
ETag: "686897696a7c876b7e"ETags can power both conditional caching and optimistic concurrency checks.
httpANYrestif-matchoptimistic-locking
http
PATCH /documents/doc_123
If-Match: "686897696a7c876b7e"If the entity tag no longer matches, the API can reject the write and ask the client to refetch.
jsonANYrestasyncjobs
json
{
"id": "job_123",
"status": "queued",
"url": "/jobs/job_123"
}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.