idempotency key
A unique value a client sends with a non-idempotent request, such as a create, so the server can recognise a retry and return the original result instead of acting twice.
In more detail
The server stores the key, a fingerprint of the request and the first response. A retry with the same key and body gets the same status, Location and body instead of a second resource. Reusing a key with a different body is rejected: the IETF draft recommends 422, and many services use 409 Conflict. Keys are scoped to the caller and expire after a documented period.
Example
In the APIs course: the fault 03-non-idempotent-retry makes two retries with one key create two tasks, and the service answers 409 for a reused key with a changed body.Related terms
- idempotency — The property of an operation that gives the same result whether you run it once or many times, because a repeat run finds nothing left to do.
- request fingerprint — A value, often a hash, calculated from the important parts of a request so the server can tell whether a repeated request is really the same one.
- 409 Conflict — The HTTP status meaning the request conflicts with the current state of the resource.
- retry — Sending a request again after it failed or timed out, in the hope that it succeeds the second time.
- replay — Delivering or returning something again: a stored result for a repeated request, or past events for a client that missed them.
- unique constraint — A constraint that no two rows may have the same value in a column or combination of columns.
Taught in
- Cookies And CORS — Modern API Architecture: REST, GraphQL & gRPC
- Idempotency Keys — Modern API Architecture: REST, GraphQL & gRPC
- Idempotency, And Exactly Once As A Fiction — Scalable System Design & Distributed Architecture
- Retries, Backoff And Jitter — Scalable System Design & Distributed Architecture
- Monolith Versus Services: The Honest Trade Offs — Scalable System Design & Distributed Architecture
- Observability As A Design Input — Scalable System Design & Distributed Architecture
- Worked Design One: Ticket Booking, Correctness First — Scalable System Design & Distributed Architecture
- Worked Design Two: A Global Chat System — Scalable System Design & Distributed Architecture