Idempotency

Idempotency

Idempotency means: no matter how many times you perform the same operation, the final result stays the same.

Think of it as:

“Do it once or do it 100 times, the outcome should not change.”

An operation is Idempotent if executing it multiple times has the same effect as executing it once.

Real-life Example:

Pressing the elevator “up” button:

• Press it once -> elevator comes
• Press it 10 more times -> nothing extra happens. The final outcome (elevator coming) stays the same.

This is Idempotency.

Idempotency in Computing

When computers talk to each other over networks, messages sometime get:

• Delayed
• Lost
• Replayed
• Retransmitted due to network timeouts

To ensure systems behave correctly despite these issues, certain operations must be idempotent.

Think of a retry:

“Do it again, but don't do extra work.”

This prevents:

• Duplicate payments
• Duplicate bookings
• Duplicate database writes
• Multiple account creations
• Double inventory reduction

HTTP Methods and Idempotency

Implementing Idempotency

To implement idempotency, the system must ensure:

If the same request comes again (same idempotency key), return the same result and do NOT perform the operation again.

This is done through three core components:

1 Idempotency Key

An idempotency key is a unique identifier for each operation request. It recognizes repeat attempts of the same operation and ensures that it is executed only once.

Client Generates the Idempotency Key (Most Common)

This is what 90% of real-world APIs use:

Why client generates?

• Client controls retries
• Client knows when it is resending a request
• Client can generate a simple UUID

Example:

Client generate a UUID

Idempotency-Key: f4c1d1c3-384a-4de8-a4c4-9cdd3012580e

Client sends this with the request:

POST /pay
Idempotency-Key: f4c1d1c3-384a-4de8-a4c4-9cdd3012580e

Server stores the result of the request using this key:

Server does NOT calculate anything. It just:

1. Checks if key is already used
2. If used -> return stored response
3. If not -> process and store response

If the key comes again:

Server simply returns the same stored result, without reprocessing the logic. This makes POST behave like an idempotent operation.

Here, the key is generated by the client only.

this is the recommended and modern approach

Server Calculates Idempotency Key (Less Common)

Used in legacy APIs or private systems where clients don't provide a key.

Here, the server calculates its own key like this:

key = SHA256(method + url + request_body)

This means:

• If the exact request is retried, the hash is the same -> idempotent
• But if anything changes in the request, a new hash gets generated -> reprocessed

Here, the server generates the key.

But this method is NOT popular now because:

• Small changes produce different hashes
• Client cannot choose how long the request should be idempotent
• Harder to handle retries across devices
• Not ideal for payments

2 Request Storage (Idempotency Store)

Server keeps a record of processed keys in a database/cache.

This store records:

• Idempotency key
• Request payload (optional)
• Operation result
• Status (success/failure/in-progress)
• Timestamp for expiry

Technologies used:

• Redis (best for fast idempotency checks)
• PostgreSQL/MySQL
• DynamoDB
• In-memory store (not recommended)

Why store the response?

So that when a duplicate request arrives, server can return the same output without running the logic again.