Idempotency
The property of an operation where performing it multiple times has the same effect as performing it once, essential for reliable API design.
Detailed Explanation
Idempotency ensures that repeating a request produces the same result. This is critical for reliability: if a client sends a request and the connection drops before receiving a response, the client can safely retry the idempotent request without fear of duplicate side effects.
HTTP methods have inherent idempotency: GET, PUT, and DELETE are idempotent; POST and PATCH are not by default. For non-idempotent operations (like creating an order), implement idempotency keys: the client generates a unique key, and the server uses it to deduplicate requests.
Why It Matters
Idempotency is essential for reliable distributed systems. It enables safe retries, prevents duplicate operations, and is critical for payment processing and financial transactions.
Real-World Example
When you click "Pay" twice on a website, an idempotently designed payment API ensures you are charged only once. The second request returns the same result as the first without creating a duplicate charge.
When to Use
For all API endpoints that create or modify resources. Implement idempotency keys for POST endpoints and ensure PUT/DELETE are naturally idempotent.
Advantages
- Safe retries without duplicate side effects
- Reliable distributed communication
- Essential for payment and financial systems
- Simplifies error recovery
- Enables at-least-once delivery
Disadvantages
- Requires server-side idempotency key storage
- Idempotency keys need expiration policies
- Adds complexity to API design
- Not all operations can be idempotent
- Storage overhead for idempotency tracking
Frequently Asked Questions
Which HTTP methods are idempotent?
GET, PUT, and DELETE are naturally idempotent. POST and PATCH are not. Making POST idempotent requires idempotency keys. HEAD and OPTIONS are also idempotent.
How do I implement idempotency keys?
The client generates a unique key (UUID) and includes it in the request header. The server checks if the key has been seen before. If yes, return the cached response. If no, process the request and store the key with the response.
How long should idempotency keys be stored?
Typically 24-48 hours. After that, the client should generate a new key. Storage can be Redis (fast, with TTL) or the database. The key duration should match your retry window.
Is GET idempotent?
Yes. GET requests should not have side effects. Calling GET multiple times returns the same data. If your GET endpoint modifies state, it violates REST principles and idempotency.
Can I make a webhook handler idempotent?
Yes. Use the event ID from the webhook as an idempotency key. Store processed event IDs and skip already-processed events. This prevents duplicate processing from webhook retries.