Glossary Term
Idempotent
Learn what idempotent means in HTTP. Understand why GET, PUT, and DELETE are idempotent, why POST is not, and how idempotency affects API design.
On this page
TL;DR: An HTTP method is idempotent when sending the same request twice has the same intended effect on the server as sending it once. GET, HEAD, OPTIONS, TRACE, PUT and DELETE are idempotent; POST and PATCH aren’t guaranteed to be. The responses to each attempt are allowed to differ.
The Core Idea
Say an API takes replacement text at a known URL:
curl -i -X PUT 'https://api.example.com/documents/notes' \
-H 'Content-Type: text/plain' --data-binary 'Reviewed'Send it twice and the document ends up with the same text either way. The first response might be 201 and the second 204. Idempotency is about the end state, not the status codes.
RFC 9110 §9.2.2 scopes the guarantee to the effect the user asked for. The server is free to log every request or keep a revision history.
Safe And Idempotent Are Not The Same
A safe method is one where the client isn’t asking for any state change. GET, HEAD, OPTIONS and TRACE are defined as safe, and they’re idempotent too. PUT and DELETE are idempotent but not safe, because changing state is the whole point of them.
A GET that returns a different price tomorrow is still idempotent. The client never asked for the price to change.
Why APIs Care About This
When a connection drops before the response arrives, the client can’t tell whether the server committed the write. With an idempotent method, it can just retry without multiplying the effect. A plain POST that creates an order gives you no such promise from the protocol.
Idempotency only covers repeats. A retry may fail, someone else may edit the resource between your attempts, and concurrent writes may conflict. Use If-Match for version-sensitive writes, and follow the API’s documented retry policy for POST.
Common Examples
| Request | Effect of an identical repeat |
|---|---|
GET /documents/notes | Retrieve again; newer content is possible. |
PUT /documents/notes with the same text | Set the same desired representation. |
DELETE /documents/notes | Keep the target removed; a repeat can return 404 after the first 204. |
POST /orders | Can create another order unless the API deduplicates it. |
These assume nobody else recreates or changes the target between attempts.
PATCH Needs Extra Care
A merge patch that sets {"status":"archived"} is idempotent. A JSON Patch add targeting /tags/- appends a new element every time it runs. The patch format and its operations decide the effect, not the PATCH method itself.
A POST endpoint can add deduplication at the application level with an idempotency key. The server has to implement it; sending the header to an endpoint that doesn’t changes nothing.
Related
Frequently asked questions
What does idempotent mean in HTTP?
Idempotent means identical repetitions have the same intended effect on server state as one request. It does not require identical status codes or content.
Which HTTP methods are idempotent?
GET, HEAD, OPTIONS, TRACE, PUT, and DELETE are defined as idempotent. PATCH and POST can implement idempotent application behavior but have no general protocol guarantee.
Why is idempotency important?
When a connection drops and you cannot tell whether the request landed, you can safely retry an idempotent request without doubling its effect. Other clients can still change the resource between attempts, so use If-Match for version-sensitive writes.
Is DELETE always idempotent?
Yes. After the first DELETE the resource is gone, and a second DELETE leaves it gone, even if it returns 404 instead of 204. How it erases the stored data is up to the server.
Sources
Related
Idempotency Key (Safe POST Retries)
An Idempotency-Key header lets a client safely retry a POST: the server stores the first result and replays it. Learn the protocol, edge cases and conflicts.
Content Negotiation
Content negotiation lets one URL serve different formats, languages or encodings based on Accept headers. See q-values, Vary, 406 and the caching traps.
HTTP Header
Learn what HTTP headers are and how they provide metadata about requests and responses. Understand common headers like Content-Type and Authorization.
HTTP Method
Learn what HTTP methods are and how they define actions on resources. Understand GET, POST, PUT, DELETE, PATCH, and other methods with examples.