idempotency

API Design

Meaning

Idempotency is a property of an operation whereby applying it once or multiple times produces the same observable result. It addresses the pain point of safely retrying failed requests in unreliable networks without causing duplicate side effects such as double charges or duplicate records. The trigger is designing APIs, message handlers, or database operations that may be retried by clients or by infrastructure.

Primary Function

API design

Communicative Purpose

Ensures repeated execution of an operation yields the same result as a single execution, enabling safe retries without duplicate side effects.

Pattern

operation → execute repeatedly → observe same final state as single execution

Função primária

API design

Propósito comunicativo

Ensures repeated execution of an operation yields the same result as a single execution, enabling safe retries without duplicate side effects.

Situações de gatilho

Distributed systems: designing retry logic for network calls that may fail mid-execution REST APIs: defining HTTP methods or RPC operations that clients can safely retry Message queues: handling duplicate message delivery from at-least-once brokers

Contextos

REST APIs, distributed systems, message brokers, payment processing, cloud infrastructure, database operations

Padrão

operation → execute repeatedly → observe same final state as single execution

Colocados típicos

HTTP PUT/DELETE methods
idempotency keys
retry policies
at-least-once delivery
exactly-once semantics
safe retries

Substituições comuns

Exactly-once semantics (stronger guarantee but harder to implement)
at-least-once delivery with deduplication (practical alternative that relies on idempotent consumers)

Erros comuns

Confusing idempotency with atomicity — idempotency concerns repetition, not transaction boundaries; assuming all GETs are safe to retry because they are read-only — handlers with side effects break idempotency; using POST for operations that should be idempotent without supplying an idempotency key; believing idempotency means no side effects — it means repeatable side effects, not absent ones; implementing idempotency only at the protocol layer without server-side state tracking for the key window

Similar / contraste

Atomicity: all-or-nothing execution vs. idempotency's repeatable execution; Determinism: same input produces same output vs. idempotency's same result across repeated calls; Exactly-once delivery: guarantees single processing vs. idempotency's tolerance of duplicates

Interferências

Coming from functional programming: may conflate idempotency with pure functions — idempotent operations can have side effects as long as repeated application yields the same observable state; Coming from SQL: may assume all UPDATE statements are idempotent — UPDATEs are only idempotent when they set values to fixed targets, not relative changes like increment

Família do chunk

at-least-once delivery
exactly-once semantics
retry policies
idempotency keys
safe retries

Nuance

When NOT to use: when you genuinely need to count executions (metering, per-call billing, audit trails). Performance: requires server-side state (idempotency keys with TTL) which adds storage and lookup overhead per request. Boundary: idempotency is scoped to observable external state — internal counters, logs, or timestamps may legitimately differ across repetitions.

Efeito pragmático

Enables safe client and infrastructure-level retries in unreliable networks without duplicate charges, duplicate records, or inconsistent downstream state.

Dica de memória

Idempotency: like pressing an elevator call button multiple times — the elevator still arrives just once, regardless of how many times you pressed.

Upgrade path

Exactly-once semantics, distributed transactions, saga pattern

Frequência: HighFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

# HTTP DELETE is idempotent by contract import requests # First call: deletes the resource response1 = requests.delete('https://api.example.com/users/42') print(response1.status_code) # 204 # Repeated calls: same observable result, no duplicate side effects response2 = requests.delete('https://api.example.com/users/42') print(response2.status_code) # 204 (or 404, but no duplicate deletion)

# Idempotency key in a payment API to prevent double-charging on retry import requests import uuid idempotency_key = str(uuid.uuid4()) payload = {'amount': 4999, 'currency': 'usd', 'source': 'tok_visa'} headers = {'Idempotency-Key': idempotency_key} # Client retries after a network timeout — server returns the cached result response = requests.post( 'https://api.stripe.com/v1/charges', json=payload, headers=headers, ) print(response.json()['id']) # Same charge id on every retry within the key window

# Idempotent database upsert: repeated execution yields the same row state import sqlite3 conn = sqlite3.connect('app.db') conn.execute(''' CREATE TABLE IF NOT EXISTS user_settings ( user_id INTEGER PRIMARY KEY, theme TEXT NOT NULL ) ''') # INSERT ... ON CONFLICT is idempotent: setting theme='dark' repeatedly # leaves the row in the same state, unlike theme = theme + 1 for _ in range(3): conn.execute( 'INSERT INTO user_settings (user_id, theme) VALUES (?, ?) ' 'ON CONFLICT(user_id) DO UPDATE SET theme = excluded.theme', (7, 'dark'), ) conn.commit() row = conn.execute('SELECT theme FROM user_settings WHERE user_id = 7').fetchone() print(row[0]) # 'dark' — identical regardless of repetition count