Idempotency
Idempotency is the property of an operation where performing it multiple times with the same inputs produces the same outcome as performing it once; HTTP GET, PUT, and DELETE are defined as idempotent by specification; Idempotency is especially critical for payment and provisioning APIs where duplicate executions cause real harm
Idempotency is the property of an operation where performing it multiple times with the same inputs produces the same outcome as performing it once. In API design, idempotent endpoints allow clients to safely retry requests after network failures without fear of duplicate side effects.
How it works
HTTP GET, PUT, and DELETE are defined as idempotent by specification. For non-idempotent POST operations, providers often support an Idempotency-Key header: the client generates a unique key per logical operation, and the server deduplicates requests with the same key, returning a cached response for retries.
Key facts
- Idempotency-Key header: A client-generated UUID that servers use to deduplicate POST requests within a time window
- GET, PUT, DELETE: HTTP defines these methods as idempotent; POST is not idempotent by default
- Deduplication window: Servers typically cache idempotency keys for 24 hours before expiring them
For builders
Idempotency is especially critical for payment and provisioning APIs where duplicate executions cause real harm. Building idempotent APIs and consumers that supply idempotency keys makes retry logic safe to implement aggressively.
Sources
- IETF. RFC 9110: HTTP Semantics. datatracker.ietf.org
- IETF. RFC 9112: HTTP/1.1. datatracker.ietf.org
- Fielding, R. (2000). Architectural Styles and the Design of Network-based Software Architectures (REST). UC Irvine. ics.uci.edu
- OWASP. API Security Top 10 (2023). owasp.org
- MDN Web Docs. HTTP reference. developer.mozilla.org
