Designing Idempotent APIs with Global Unique IDs: UUID vs Snowflake

Idempotent Design

Idempotency means that executing an operation any number of times yields the same effect as executing it once. An idempotent API can be called repeatedly with the same parameters and always return the same result.

Why Do APIs Need Idempotency?

When a client calls an API, the possible outcomes are success, failure, or timeout. For success and failure the client can act accordingly, but a timeout leaves the client uncertain whether the request succeeded, so the client typically retries, which may cause multiple executions.

Example: when creating an order, inventory must be decreased. If the inventory‑decrease request times out and the client retries, the system must ensure the inventory is not deducted twice.

Two Common Approaches

The provider offers a query interface so the client can check after a timeout whether the operation succeeded. This puts the responsibility on the client and can be risky for third‑party APIs.

The API itself supports idempotency, shifting the guarantee entirely to the provider.

Global ID

To make an API idempotent without an extra query, a globally unique identifier can be added to the request. The database table stores this identifier with a unique index; duplicate inserts trigger a uniqueness error, indicating the request has already been processed.

How to generate the global ID?

1. Central Allocation Service

Pros: decouples ID generation from business clusters.

Cons: requires a highly available service, increasing maintenance cost.

2. Integrated Generation in Business Service Cluster

Pros: the business cluster is already highly available, no extra guarantees needed.

Cons: ID generation is coupled with business logic, but this is usually acceptable.

Generally the second approach is preferred; the key is an algorithm that can generate a globally unique ID across the cluster.

Desirable properties (not mandatory):

Monotonically increasing on each machine (helps database performance).

Clear bit‑level rules for traceability.

Common Global ID Algorithms

UUID

UUIDs provide a universally unique identifier without a central coordinator. They are easy to generate locally, have good performance, and are widely supported.

Advantages: simple implementation, local generation, good performance, high scalability.

Disadvantages: not sequential (can affect database indexing), relatively long (more storage).

UUIDs are suitable for small‑to‑medium projects where database load is not a bottleneck.

Snowflake

Snowflake, originally from Twitter, generates 64‑bit integer IDs with the following structure:

1 bit: fixed 0, ensuring the ID is positive.

41 bits: timestamp in milliseconds (covers ~69 years).

10 bits: machine identifier (5 bits data‑center ID, 5 bits machine ID), supporting up to 1,024 instances.

12 bits: sequence number, allowing up to 4,096 IDs per millisecond per machine.

Advantages: sequential and time‑ordered, high performance, configurable bit allocation.

Disadvantages: depends on synchronized clocks; clock drift across machines can cause duplicate IDs.

Under high concurrency, Snowflake IDs outperform UUIDs in storage and retrieval speed. Many Chinese companies have their own Snowflake‑based implementations, such as Baidu's UidGenerator.

Business Logic Integration

When the database reports a unique‑constraint violation, it indicates the request has already succeeded, so the service can simply return the previous result without re‑executing the business logic.

HTTP Idempotency

HTTP methods have different idempotency guarantees. POST requests can be retried due to network issues, leading to duplicate submissions.

Common solution: include a globally unique ID in the request payload (obtained from the backend beforehand). The server uses this ID to enforce idempotency, and after a successful operation the client redirects to a GET request to display the result.

Conclusion

This article covered the key points of idempotent design, presented two main implementation strategies, and compared UUID and Snowflake algorithms for generating globally unique identifiers that enable reliable, high‑performance API idempotency.