Idempotency
- Pronunciation
- eye-dem-POH-tun-see
In short
Idempotency is the property of an operation that produces the same result whether it runs once or many times, so accidentally repeating a request is safe.
What is idempotency?
An operation is idempotent if doing it twice, or a hundred times, leaves the system in the same state as doing it once. Setting a user's email to ada@example.com is idempotent, because repeating it changes nothing after the first time, while adding $10 to a balance is not, because every repeat adds another $10. A light switch with separate on and off buttons is a good analogy: pressing on twice still just leaves the light on.
Idempotency matters because networks are unreliable. A client may send a payment request, lose the connection before the response arrives, and retry without knowing whether the first attempt succeeded, and message queues and webhooks may deliver the same message more than once. If the operation is idempotent, those retries are harmless instead of charging the customer twice.
In HTTP, methods such as GET, PUT, and DELETE are defined as idempotent, while POST is not and PATCH is not guaranteed to be. To make POST requests safe to retry, many APIs, especially payment APIs, accept an idempotency key: a unique ID the client sends in a header such as Idempotency-Key. The server stores each key with its result, so a repeated request with the same key returns the original response instead of running again.
Idempotent does not mean the response is always identical: deleting a resource twice may return 204 No Content the first time and 404 Not Found the second, yet the state of the server is the same. Idempotency is also different from being safe, the HTTP term for methods like GET that don't change anything at all, so DELETE is idempotent but not safe.
At a glance
Key takeaways
- An idempotent operation has the same effect no matter how many times it runs.
- It makes retries safe after timeouts, crashes, and duplicate messages.
GET,PUT, andDELETEare idempotent in HTTP;POSTis not.- Idempotency keys let APIs safely retry non-idempotent requests such as payments.
- Responses may differ between calls; what stays the same is the resulting state.
Example
// Run each payment only once per idempotency key (Express.js)
app.post("/api/payments", async (req, res) => {
const key = req.get("Idempotency-Key");
if (!key) return res.status(400).send("Missing Idempotency-Key header");
const saved = await db.idempotencyKeys.find(key);
if (saved) return res.status(saved.status).json(saved.body); // replay, don't charge again
const payment = await chargeCard(req.body);
await db.idempotencyKeys.save(key, { status: 201, body: payment });
res.status(201).json(payment);
});Readers ask
Which HTTP methods are idempotent?
GET, HEAD, OPTIONS, TRACE, PUT, and DELETE are idempotent according to the HTTP specification. POST is not, and PATCH is not guaranteed to be, although a specific API can design them to behave idempotently.
What is an idempotency key?
An idempotency key is a unique value, often a UUID, that the client sends with a request, typically in an Idempotency-Key header. The server remembers each key and its result, so a retried request with the same key returns the stored response instead of repeating the action.
What is the difference between safe and idempotent HTTP methods?
A safe method, such as GET, doesn't change data on the server at all. An idempotent method may change data, but repeating it has no further effect, so every safe method is idempotent while PUT and DELETE are idempotent without being safe.
See also
- REST APIBackend & APIs, p. 38A REST API is a web API that exposes data as resources identified by URLs and lets clients read or change them using standard HTTP methods.
- HTTPWeb Development, p. 19HTTP is the protocol that browsers, apps, and servers use to exchange web pages and data through a simple cycle of requests and responses.
- Message QueueBackend & APIs, p. 29A message queue is a component that stores messages from one service until another is ready to process them, so parts of a system can work asynchronously.
- WebhookBackend & APIs, p. 47A webhook is an automated HTTP request that one application sends to a URL you provide as soon as a specific event happens, such as a completed payment.
- TransactionDatabases, p. 47A transaction is a group of database operations that succeed or fail as a single unit, so the data is never left in a half-finished, inconsistent state.
- APIBackend & APIs, p. 2An API is a set of rules that lets one piece of software request data or actions from another in a predictable, documented way.
Sources
Spotted a mistake or something missing on this page?Suggest an edit