REST Verb Semantics Lab (Interactive)
Replay N identical requests per HTTP verb and watch server state, status codes, and created resources diverge. Fire GET, POST, PUT, PATCH, or DELETE at noun-based routes repeatedly to see which verbs guarantee f(f(x)) = f(x) and which create duplicate invoices on every retry.
REST Verb Semantics & Idempotency Replay
Fire N identical requests at a route and watch safe, idempotent, and non-idempotent behavior diverge.
POST /v1/invoices
Retry 1 → 201 Created
Retry 2 → 201 Created
Retry 3 → 201 Created
Invoices created
3
Final state
deleted
Safe / Idemp
no / no
How It Works Under the Hood
REST models systems as plural nouns manipulated through standardized verbs, and each verb carries RFC-mandated safety and idempotency promises. GET is safe and cacheable, PUT replaces an entity so replays land on identical server state, DELETE removes so later calls simply 404, but POST appends a fresh resource every single time. Real networks drop responses constantly, so understanding which verbs are safe to auto-retry is what separates APIs that survive flaky mobile connections from ones that double-charge customers.
Core Architectural Principles
- Idempotent methods (GET, PUT, DELETE) produce the same server state for N identical requests as for one.
- POST is non-idempotent: each retry appends a new resource and returns 201 Created with a Location header.
- Errors must use accurate 4xx codes with RFC 9457 problem-details bodies, never 200 OK with an error string.
When designing a mutation API, explicitly label each endpoint safe/idempotent or not, and explain retries: PUT and DELETE can be replayed by client SDKs freely, POST cannot — that is why payment APIs demand idempotency keys. Mention returning 405 for verbs on wrong route shapes and keeping nesting at two URI levels.
Strict verb semantics add contract discipline but buy free caching, automatic retries, and intermediary-visible error handling.