Idempotencia: reglas y conceptos
Este artículo es una explicación de conceptos sobre idempotencia en HTTP/REST, incluyendo preguntas de examen, ejemplo práctico y referencias.
Resumen rápido
La idempotencia significa que una operación idéntica puede ejecutarse cualquier número de veces con el mismo resultado (formalmente: f(f(x)) = f(x)). En HTTP/REST es fundamental para reintentos seguros, tolerancia a fallos y control de efectos secundarios.
Descripción técnica concisa
La idempotencia es una propiedad de una operación, no solo de un endpoint. En HTTP, GET/HEAD/PUT/DELETE se consideran idempotentes (GET/HEAD además son “seguras”). POST no es idempotente, pero puede hacerse idempotente mediante patrones como Idempotency Key.
Es importante distinguir:
- Segura: sin cambio de estado en el servidor (por ejemplo, GET)
- Idempotente: repetir la operación no genera efectos secundarios adicionales (por ejemplo, PUT)
Para actualizaciones concurrentes, ayudan ETag + If-Match (si no, por ejemplo 412 Precondition Failed). En sistemas distribuidos con reintentos, la idempotencia es obligatoria.
Puntos clave para exámenes
- Definición
f(f(x)) = f(x); propiedad de la operación - HTTP: GET/HEAD segura+idempotente; PUT/DELETE idempotente; POST no idempotente
- Hacer POST idempotente: Idempotency Key + almacén de deduplicación + respuestas deterministas
- Códigos de estado: 200/201/204, 409 Conflict, 412 Precondition Failed, 429 Too Many Requests
- IHK: efectos secundarios rastreables, IDs de correlación, reglas de reintento documentadas
- Seguridad: protección contra replay (keys con límite temporal, firmas)
- Rentabilidad: menos dobles registros/soporte
- Documentación: OpenAPI describe idempotencia/keys/TTL/catálogo de errores
Componentes principales
- Segura vs idempotente
- Semántica de métodos (GET/PUT/PATCH/DELETE/POST)
- ETag + If-Match
- Almacén de deduplicación (Key → Response) con TTL
- Conflictos/códigos de error (409/412)
- Idempotency Key por caso de negocio
- Patrón Outbox/Inbox
- Estrategia de reintento (Backoff, 429/Retry-After)
- Observabilidad (IDs de correlación)
- Pruebas (reintentos/pruebas de paralelismo)
Ejemplo práctico (POST idempotente)
POST /payments
Headers: Content-Type: application/json
Idempotency-Key: pay-123-abc
Body: { "orderId": 42, "amount": 59.98, "method": "card" }
Servidor:
- si la key ya existe → devolver respuesta almacenada
- si no → crear pago, almacenar respuesta (TTL por ejemplo 24h)
Ventajas y desventajas
Ventajas
- Reintentos seguros
- Protección contra dobles registros
- Integraciones más robustas
Desventajas
- Almacén de deduplicación + complejidad lógica
- La semántica/TTL debe estar claramente definida
Preguntas típicas de examen (con respuesta breve)
- ¿Segura vs idempotente? Segura = sin cambio de estado; idempotente = repetible sin efectos secundarios adicionales.
- ¿Cómo haces POST idempotente? Idempotency Key + almacén de deduplicación + respuestas deterministas.
- ¿Rol de ETag/If-Match? Protección contra pérdida de actualizaciones; en caso de conflicto, 412.
- ¿Qué riesgos sin idempotencia? Efectos secundarios duplicados (pagos), inconsistencias, altos costos de soporte.
Respuesta libre
La idempotencia es la base para sistemas robustos con reintentos y timeouts. Documenta la semántica por operación, incluyendo códigos de estado permitidos en reintentos y TTL de las keys. En sistemas de mensajería, los consumidores deben ser idempotentes (Inbox/Outbox).
Estrategia de aprendizaje
- Analizar APIs públicas de pagos (Idempotency Keys).
- Crear diagramas de estado para PUT/DELETE/POST.
- Asociar códigos de estado/headers a escenarios.
- Garantizar respuestas deterministas.
Análisis del tema
- Núcleo: semántica de métodos, deduplicación
- Desafíos: efectos secundarios, condiciones de carrera
- Seguridad: protección contra replay
- Documentación: OpenAPI + catálogo de errores
- Rentabilidad: menos incidentes