httpANYhttpgetsafe
http
GET /products/sku_123GET 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.
httpANYhttppostcreate
http
POST /ordersPOST is not inherently idempotent. Repeating the same request may create duplicates unless you add idempotency controls.
httpANYhttpputidempotent
http
PUT /profiles/123PUT is generally idempotent: sending the same representation repeatedly should lead to the same final state.
httpANYhttppatchpartial-update
http
PATCH /profiles/123PATCH may or may not be idempotent depending on the patch format and operation design.
httpANYhttpdeleteidempotent
http
DELETE /profiles/123DELETE is commonly designed to be idempotent: deleting an already-deleted resource should not keep changing state.
httpANYhttpheadheaders
http
HEAD /reports/monthly.pdfHEAD can be useful for existence checks, cache validation, or content-length inspection.
httpANYhttpoptionscors
http
OPTIONS /usersOPTIONS is often used by browsers for CORS preflight requests and by tooling to inspect server capabilities.
Idempotency patterns
Protect writes from accidental duplication.
httpANYrestpostidempotency-key
http
POST /payments
Idempotency-Key: 8f3dc9d4-7d3e-4c66-9f44-7d85f0f86dd1This pattern helps clients safely retry network-failed POST requests without creating duplicate side effects.
httpANYrestputupsert
http
PUT /devices/device_123When the client supplies the stable identifier, repeated PUT requests can converge on the same final state.
jsonANYrestpatchjson
json
{
"display_name": "Jane Smith",
"timezone": "America/Los_Angeles"
}Field assignment patches are easier to reason about than increment-style or append-style patches when idempotency matters.
textANYrestgetanti-pattern
text
Avoid: GET /posts/123/mark-readA 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.