Idempotent endpoints

API Design

Meaning

Idempotent endpoints are HTTP API endpoints that produce the same result regardless of how many times the same request is made, even when retries occur. They address the pain point of network failures causing clients to retry requests, which without idempotency would create duplicate side effects like double-charges or duplicate records. The trigger is designing any mutating endpoint that may be retried by clients, proxies, or message brokers in distributed systems.

Primary Function

API design

Communicative Purpose

Ensures that repeated identical requests produce the same outcome as a single request, preventing duplicate side effects from client retries and at-least-once delivery.

Pattern

design endpoint → ensure repeated identical requests yield same result → use idempotency keys for non-naturally-idempotent verbs

Função primária

API design

Propósito comunicativo

Ensures that repeated identical requests produce the same outcome as a single request, preventing duplicate side effects from client retries and at-least-once delivery.

Situações de gatilho

REST API design: implementing PUT or DELETE endpoints that may be retried by clients or proxies

Contextos

REST APIs, microservices, distributed systems, payment gateways, message queues, HTTP middleware

Padrão

design endpoint → ensure repeated identical requests yield same result → use idempotency keys for non-naturally-idempotent verbs

Colocados típicos

HTTP PUT
HTTP DELETE
idempotency key
retry logic
at-least-once delivery
exactly-once semantics
request fingerprint

Substituições comuns

Natural idempotency (PUT replaces resource state) vs. idempotency tokens (POST with key) — natural is simpler but only fits resource-replacement semantics
tokens generalize to any verb at the cost of storage

Erros comuns

Assuming POST is always non-idempotent: POST can be made idempotent with idempotency keys, though it requires extra coordination

Similar / contraste

Idempotent vs. safe operations: idempotent allows side effects on first call; safe forbids all side effects

Interferências

Coming from SQL: may assume database transactions alone guarantee endpoint idempotency — network retries between client and server require application-level idempotency keys stored alongside the request

Família do chunk

REST API design
HTTP semantics
retry strategies
idempotency keys
at-least-once delivery

Nuance

Don't apply to read-only endpoints that need fresh data each call; performance overhead of idempotency key storage and lookup must be weighed against retry frequency; partial failures mid-request can leave the system in an inconsistent state even with idempotent design

Efeito pragmático

Enables safe client retries without duplicate charges, duplicate orders, or inconsistent state in distributed systems, reducing the need for manual reconciliation.

Dica de memória

Idempotent endpoints are like a vending machine with a reliable coin return — pressing the button twice with the same coin still gives you one snack, no matter how many times you press.

Upgrade path

Exactly-once semantics, saga pattern, outbox pattern, distributed transactions

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

Examples

from flask import Flask, request, jsonify app = Flask(__name__) users = {} @app.route('/users/<int:user_id>', methods=['PUT']) def upsert_user(user_id): user_data = request.get_json() users[user_id] = user_data return jsonify({"id": user_id, "status": "stored"}), 200

import uuid from functools import wraps from flask import request, jsonify processed_keys = {} def idempotent(view_func): @wraps(view_func) def wrapper(*args, **kwargs): key = request.headers.get('Idempotency-Key') if key in processed_keys: return jsonify(processed_keys[key]), 200 response = view_func(*args, **kwargs) processed_keys[key] = response.get_json() return response return wrapper @app.route('/payments', methods=['POST']) @idempotent def create_payment(): amount = request.json['amount'] return jsonify({"payment_id": str(uuid.uuid4()), "amount": amount}), 201

from flask import jsonify orders = {1: {"status": "pending"}, 2: {"status": "pending"}} def cancel_order(order_id): if order_id in orders: del orders[order_id] return '', 204 # Already gone — still idempotent, no error