Ensuring API Idempotency: Concepts and the “One Lock, Two Check, Three Update” Method

Idempotency, a mathematical and computer‑science concept, means that executing an operation multiple times yields the same effect as executing it once. In API design this translates to: for the same parameters, the result must remain unchanged regardless of how many times the endpoint is called.

The article distinguishes two types of idempotency: request idempotency (identical parameters produce identical responses) and business idempotency (once a business transaction reaches its final state, subsequent calls must return the same result, while before reaching that state the operation may be retried until completion).

In practice, most concerns revolve around business idempotency, such as ensuring a payment request is processed exactly once despite retries caused by network issues or system errors.

When many concurrent requests attempt the same operation, a phenomenon called “idempotent breakdown” can occur. To prevent this, the article proposes a three‑step approach—often summarized as “one lock, two check, three update”.

One lock : Acquire an exclusive lock (e.g., a Redis distributed lock) using a unique idempotency key agreed upon with upstream services.

Two check : While holding the lock, determine whether the operation has already been performed, using mechanisms such as a state machine, operation log, or unique index.

Three update : If the operation has not yet been executed, perform the business logic and persist the result, then release the lock.

The process relies on a unique idempotency identifier and should be complemented by database uniqueness constraints as a final safeguard against duplicate data.