Idempotency in Software Systems: Definitions, Real‑World Scenarios, and Implementation Strategies

1. Real‑world Idempotent Scenarios

Examples such as a user double‑clicking a QR‑code ordering button or collecting masks multiple times demonstrate how missing idempotent controls can cause duplicate orders or resource waste.

2. Mathematical Definition

In mathematics, an element is idempotent under a binary operation if applying the operation repeatedly yields the same element (e.g., 0 and 1 for multiplication, or functions where f(f(x)) = f(x)).

3. Software Definition

Idempotency is a contract of an API: multiple successful calls within a defined time window must have the same effect as a single call, and failures are considered normal with automatic retries.

4. Two Dimensions of Idempotency

• Global uniqueness: the request must carry a globally unique identifier (e.g., order number). • Temporal scope: some operations are allowed only once per defined period (hour, day, forever).

5. Idempotent Solutions

5.1 Database Operations

Insert: avoid auto‑increment IDs; use pre‑allocated IDs or business keys with existence checks, possibly protected by locks. Delete: idempotent when based on a unique ID or business key. Update: generally non‑idempotent due to cumulative changes and concurrency issues. Select: read‑only queries are inherently idempotent.

5.2 Front‑end Button Disable

Disable or show a loading state on the submit button after the first click until the API returns, preventing duplicate submissions.

5.3 Database Unique Constraints

Enforce uniqueness (e.g., invoice numbers) with a unique index; the database guarantees idempotent insertion.

5.4 Pessimistic Lock

Use a global order‑number table with SELECT ... FOR UPDATE to serialize number generation; lock is held within a transaction.

5.5 Optimistic Lock

Update statement with version check:

UPDATE table SET x=#{x}, version=version+1 WHERE pk=#{px} AND version=#{version}

If the version has changed, the update affects zero rows, achieving idempotency.

5.6 State‑Machine Control

Update status only when the current state matches the expected previous state:

UPDATE table SET status=#{newStatus} WHERE pk=#{px} AND status=#{oldStatus}

This prevents illegal state transitions and duplicate processing.

5.7 Form‑Token Approach

Generate a token (or UUID) when the form loads; on submission, the server checks whether the token was already processed, using in‑memory structures, JVM locks, or Redis SETNX for distributed environments.

5.8 Message Queue (MQ)

Treat the MQ consumption as “once only”: the producer must guarantee a single successful send, and the consumer uses the order ID as an idempotent key to ensure only one processing.

5.9 RPC Calls

For high‑frequency telemetry (e.g., delivery‑person location), use a business key such as {orderId}+{timestamp} and set an expiration twice the client timeout to detect duplicates.

6. Summary

Idempotency is not tied to distributed or high‑concurrency systems but is a design requirement for any feature that may be retried. Implementations typically involve checking previous execution state and preventing duplicate state changes before the business logic runs. Whether an API needs idempotency should be decided based on concrete business requirements.