http
GET /products/sku_123Notes
GET is safe and should not mutate state. It is commonly cacheable and bookmarkable.
REST API Methods and Idempotency
HTTP methods, safe vs unsafe semantics, and idempotency examples for API consumers and designers.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
HTTP method semantics
Map the method to the expected behavior.
POST creates or triggers processing
Submit a new resource or command-like workflow.
httpANYhttppostcreate
http
POST /ordersNotes
POST is not inherently idempotent. Repeating the same request may create duplicates unless you add idempotency controls.
http
PUT /profiles/123Notes
PUT is generally idempotent: sending the same representation repeatedly should lead to the same final state.
http
PATCH /profiles/123Notes
PATCH may or may not be idempotent depending on the patch format and operation design.
http
DELETE /profiles/123Notes
DELETE is commonly designed to be idempotent: deleting an already-deleted resource should not keep changing state.
http
HEAD /reports/monthly.pdfNotes
HEAD can be useful for existence checks, cache validation, or content-length inspection.
OPTIONS advertises supported interactions
Inspect available methods or CORS capabilities.
httpANYhttpoptionscors
http
OPTIONS /usersNotes
OPTIONS is often used by browsers for CORS preflight requests and by tooling to inspect server capabilities.
Idempotency patterns
Protect writes from accidental duplication.
Use an idempotency key for POST
Deduplicate retryable create requests.
httpANYrestpostidempotency-key
http
POST /payments
Idempotency-Key: 8f3dc9d4-7d3e-4c66-9f44-7d85f0f86dd1Notes
This pattern helps clients safely retry network-failed POST requests without creating duplicate side effects.
http
PUT /devices/device_123Notes
When the client supplies the stable identifier, repeated PUT requests can converge on the same final state.
json
{
"display_name": "Jane Smith",
"timezone": "America/Los_Angeles"
}Notes
Field assignment patches are easier to reason about than increment-style or append-style patches when idempotency matters.
Avoid mutations on GET
Do not track writes in the same endpoint contract.
textANYrestgetanti-pattern
text
Avoid: GET /posts/123/mark-readNotes
A GET endpoint should not change business state. Use a dedicated write route if you need to record events or acknowledgements.
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 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.