How to Build Idempotent APIs?
Understanding Idempotency in Distributed Systems
Why Idempotency is Important?
Idempotency refers to the property of an operation where executing it multiple times has the same effect as executing it once. Distributed systems inherently deal with unreliability. Network partitions, timeouts, server unavailability, or client crashes can interrupt communication flows. When a client sends a request but doesn't receive a timely response, it cannot be certain whether the request was processed, lost before reaching the server, or processed successfully, but the response was lost. The natural reaction is to retry the request. Without idempotency, retrying operations can cause unintended side effects like duplicate payments or incorrect data.
For example, a customer submits an order on an e-commerce platform, but a network glitch causes the client to retry the request. Without idempotency, the system might create two identical orders, charging the customer twice. An idempotent API ensures only one order is created, regardless of retries. Similarly, in financial systems, a funds transfer API must guarantee a single transfer even if the request is sent multiple times due to timeouts.
Achieving Idempotency
Implementing idempotency requires the server to detect duplicate requests. This involves tracking the state of requests using a unique identifier provided by the client, known as an Idempotency Key. The client generates a unique key (e.g., a UUID) for each distinct operation and it must send the same idempotency key for retries of the same operation (in case of failures).
When a request arrives with an idempotency key, the server checks to see if it has processed one with this key before.
Suppose the key is recognized and associated with a completed operation. In that case, the server skips executing the operation again and returns the previously generated response.
Suppose the key is recognized, but the original operation is still in progress (e.g., held by a lock). The server might wait or return a conflict/busy status in that case.
If the key is new, the server processes the request, stores the result associated with the idempotency key, and then returns the response.
Idempotency in Stateful Services
Stateful services manage idempotency by storing information about processed requests.
Database Unique Constraints
Databases provide built-in mechanisms to enforce idempotency. For example, assigning unique primary keys to entities ensures duplicate entries cannot exist. Continuing with the e-commerce example, if each order has a globally unique identifier (GUID), attempting to insert an order with the same GUID will fail due to a primary key violation. This technique works well for write-heavy systems but requires proper error handling.
Deduplicating Duplicate Requests
In distributed systems, messages may be delivered multiple times due to network issues or retries. Before processing each request, the system checks if the request's idempotency key has been seen before. For example, a message queue processing user signups might store processed message IDs in a distributed cache. If a duplicate message arrives, the system immediately skips reprocessing and acknowledges receipt.
Idempotency in Stateless Services
Stateless services cannot easily implement idempotency, as they retain no memory of past requests. Idempotency for stateless services is often handled by stateful components upstream (like an API gateway) or downstream (like ensuring the ultimate data storage operation is idempotent).
Race Conditions in Idempotent Systems
Race conditions occur when multiple processes access shared resources concurrently, potentially causing inconsistent outcomes. In distributed systems, race conditions are common due to high concurrency and network latencies. Consider a scenario where two identical requests with the same idempotency key arrive simultaneously at different server nodes. Without synchronization, both nodes might check the idempotency store, find no key, and process the payment, resulting in duplicate transactions. Mitigation strategies include:
Distributed Locking: Before processing, the service attempts to acquire a lock named after the idempotency key. Only the lock holder proceeds with processing.
Request Sharding: Using consistent hashing on the idempotency key, requests concerning the same key can be routed to the same server, reducing the need for global locks.
Fig. Request Sharding Database Transaction Isolation Levels: Transaction isolation levels (like Serializable) can lock the relevant resource (the potential row for the idempotency key) during the check-and-process phase. This forces concurrent requests for the same key to serialize.
Atomic Operations: Leverage atomic operations/commands provided by the underlying storage. The first successful insert wins; subsequent attempts fail gracefully or update a status, allowing the application to know the request was already handled.
If you enjoyed this article, please hit the ❤️ like button.
If you think someone else will benefit from this, then please 🔁 share this post.