Designing Idempotent APIs and Global Unique ID Strategies

Today we discuss the design of idempotent interfaces, where idempotency means that executing an operation any number of times yields the same effect as a single execution.

Idempotent APIs allow repeated calls with the same parameters to return identical results, which is crucial when a request times out and the client must retry.

Why Idempotency Is Needed

When a request fails due to timeout, the client cannot know whether the operation succeeded, so it retries, potentially causing duplicate effects such as subtracting inventory multiple times.

Two main solutions exist: the provider offers a query interface for the client to check the result, or the provider builds idempotency into the API itself.

Global Unique ID

To make an API idempotent without extra queries, a globally unique identifier (global ID) can be added to the request; the database enforces a unique constraint, causing a conflict on duplicate submissions, which signals that the operation has already succeeded.

Global IDs can be allocated either by a dedicated ID‑generation service (decoupled from business clusters) or directly within the business service cluster (simpler but tightly coupled).

Common Global ID Algorithms

UUID

UUIDs provide universally unique identifiers without a central coordinator. They are easy to generate, have good performance, and are widely supported, but they are not sequential and consume more storage.

Snowflake

Snowflake, originally from Twitter, generates 64‑bit integer IDs with a structure of 1 sign bit, 41 bits for timestamp, 10 bits for machine identifiers, and 12 bits for a per‑millisecond sequence, yielding up to 4096 IDs per millisecond per node.

Advantages include monotonic increase and high performance; drawbacks involve reliance on synchronized clocks, which can cause duplicate IDs if clocks drift.

Business Logic

When a unique‑key violation occurs in the database, it indicates the request has already been processed, allowing the service to return the previous result without re‑executing the business logic.

HTTP Idempotency

For HTTP POST requests that may be retried, a hidden global ID can be sent with the form. The backend checks the ID, ensuring only one successful execution, and the client can safely refresh the result via a GET request.

Conclusion

The article outlines key points of idempotent design and presents several global ID generation strategies, enabling developers to choose the most suitable approach for their systems.