Idempotency: Rules and Definitions

This article is a definition guide to idempotency in HTTP/REST – including exam questions, practical examples, and key concepts.

In a Nutshell

Idempotency means that an identical operation can be executed any number of times and produce the same result (formally: f(f(x)) = f(x)). In HTTP/REST, this is central to safe retries, fault tolerance, and controlling side effects.

Core Technical Definition

Idempotency is a property of an operation, not merely an endpoint. In HTTP, GET/HEAD/PUT/DELETE are idempotent (GET/HEAD additionally “safe”). POST is not idempotent, but can be made idempotent through patterns like Idempotency Key.

The distinction matters:

• Safe: no server-side state change (e.g., GET)
• Idempotent: repeated execution causes no additional side effects (e.g., PUT)

For concurrent updates, ETag + If-Match help prevent lost writes (returning 412 Precondition Failed on conflict). In distributed systems with retries, idempotency is essential.

Key Exam Topics

• Definition f(f(x)) = f(x); property of the operation
• HTTP: GET/HEAD safe+idempotent; PUT/DELETE idempotent; POST not idempotent
• Making POST idempotent: Idempotency Key + dedupe store + deterministic responses
• Status codes: 200/201/204, 409 Conflict, 412 Precondition Failed, 429 Too Many Requests
• IHK: traceable side effects, correlation IDs, documented retry rules
• Security: protection against replay attacks (time-limited keys, signatures)
• Cost efficiency: fewer duplicate transactions and support incidents
• Documentation: OpenAPI describes idempotency, keys, TTL, and error catalogs

Core Components

1. Safe vs idempotent
2. Method semantics (GET/PUT/PATCH/DELETE/POST)
3. ETag + If-Match
4. Dedupe store (key → response) with TTL
5. Conflict/error codes (409/412)
6. Idempotency key per business transaction
7. Outbox/Inbox pattern
8. Retry strategy (backoff, 429/Retry-After)
9. Observability (correlation IDs)
10. Tests (retry and concurrency tests)

Practical Example (Idempotent POST)

POST /payments
Headers: Content-Type: application/json
         Idempotency-Key: pay-123-abc
Body: { "orderId": 42, "amount": 59.98, "method": "card" }

Server:
- if key already exists → return stored response
- else create payment, store response (TTL e.g. 24h)

Advantages and Disadvantages

Advantages

• Safe retries
• Protection against duplicate charges
• More robust integrations

Disadvantages

• Dedupe store adds complexity
• Semantics and TTL must be clearly defined

Typical Exam Questions (with Short Answers)

1. Safe vs idempotent? Safe = no state change; idempotent = repeatable without side effects.
2. How do you make POST idempotent? Idempotency Key + dedupe store + deterministic responses.
3. Role of ETag/If-Match? Protection against lost updates; returns 412 on conflict.
4. What risks exist without idempotency? Duplicate side effects (payments), inconsistencies, high support costs.

Open-Ended Answer

Idempotency is fundamental to systems that handle retries and timeouts. Document the semantics of each operation, including allowed status codes on retry and TTL for keys. In messaging systems, consumers must be idempotent (Inbox/Outbox pattern).

Learning Strategy

1. Analyze public payment APIs (Idempotency Keys).
2. Create state diagrams for PUT/DELETE/POST.
3. Map status codes and headers to scenarios.
4. Ensure deterministic responses.

Topic Analysis

• Core: method semantics, deduplication
• Challenges: side effects, race conditions
• Security: replay protection
• Documentation: OpenAPI + error catalog
• Cost efficiency: fewer incidents

Key References

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://docs.stripe.com/idempotency