Understanding API Idempotency and How to Ensure It

In a recent incident a user’s rollback operation failed because the submit API was called twice, resulting in identical states and exposing the need for idempotent interfaces.

What is API Idempotency?

Idempotency, originally a mathematical term, means that sending the same request to an interface multiple times must result in the operation being executed only once. Without it, repeated calls (e.g., payment or order creation) can cause serious issues such as double charging.

Why Do Idempotency Problems Occur?

Network fluctuations causing duplicate requests.

User accidental or intentional repeated actions (multiple clicks, back button, refresh).

Retry mechanisms (Nginx, RPC, business‑level retries).

Scheduled tasks executing multiple times.

Browser history or back‑forward navigation submitting forms again.

Duplicate HTTP requests from the browser.

Double‑clicking submit buttons.

How to Ensure API Idempotency?

The solutions are divided into client‑side prevention and server‑side verification, with the latter being more reliable.

Button can be operated only once After submission, disable the button or show a loading state to prevent repeated clicks.

Token mechanism Generate a token when the page loads, attach it to every request, and let the backend reject duplicate tokens.

Post/Redirect/Get (PRG) pattern After a form POST, redirect to another page to avoid resubmission on refresh or back/forward navigation.

Store a special flag in session Generate a unique identifier, store it in the session, and include it as a hidden field in the form; the server processes the request only if the identifier matches and then removes it.

Unique index in the database Use a unique constraint (e.g., on order number) so duplicate inserts fail automatically.

Optimistic lock Update statements include a version check, e.g., update table set version = version + 1 where id = #{id} and version = #{version} . The first request increments the version; a concurrent request fails because the version no longer matches.

Select + insert/update/delete Check existence before performing the operation; suitable for single‑JVM scenarios but not reliable in distributed environments without additional locking.

Distributed lock Use external systems like Redis or Zookeeper to acquire a global lock before modifying data, ensuring only one instance proceeds.

State‑machine idempotency Design business processes as finite state machines; if an entity is already in the target state, further requests are ignored.

Idempotent table (anti‑duplicate table) Insert a unique key (e.g., order number) into a dedicated table before processing; if insertion fails, reject the request.

Buffer queue Enqueue incoming requests and process them asynchronously, filtering duplicates during consumption.

Global unique identifier Combine source information with a unique sequence number; the backend checks this identifier to allow only one execution.

References: articles on idempotency concepts, distributed system implementations, and high‑concurrency solutions.