Idempotence: Rules and Terminology

This article is a definition of terms for idempotence in HTTP/REST – including exam questions, practical example, and tags.

In a Nutshell

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

Compact Technical Description

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

It is important to distinguish:

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

For competing updates, ETag + If-Match help (otherwise e.g. 412 Precondition Failed). In distributed systems with retries, idempotence is a must.

Exam-Relevant Key Points

• Definition f(f(x)) = f(x); property of the operation
• HTTP: GET/HEAD safe+idempotent; PUT/DELETE idempotent; POST not idempotent
• Make POST idempotent: Idempotency Key + Dedupe Store + deterministic responses
• Status codes: 200/201/204, 409 Conflict, 412 Precondition Failed, 429 Too Many Requests
• Chamber of Commerce: traceable side effects, correlation IDs, document retry rules
• Security: protection against replay (time-limited keys, signatures)
• Cost-effectiveness: fewer duplicate bookings/support
• Documentation: OpenAPI describes idempotence/keys/TTL/error catalog

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. Conflicts/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/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
- otherwise create Payment, store response (TTL e.g. 24h)

Advantages and Disadvantages

Advantages

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

Disadvantages

• Dedupe Store + logic/complexity
• Semantics/TTL must be clearly defined

Typical Exam Questions (with Short Answer)

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

Free Answer

Idempotence is the foundation for robust systems with retries/timeouts. Document the semantics per operation, including permitted status codes on retry and key TTL. In messaging systems, consumers must be idempotent (Inbox/Outbox).

Learning Strategy

1. Analyze public payment APIs (Idempotency Keys).
2. Create state diagrams for PUT/DELETE/POST.
3. Map status codes/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-effectiveness: fewer incidents

Most Important Sources

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