Reglas de Idempotencia - HTTP, REST API, Idempotency Key y ETag
Este artículo es una explicación conceptual sobre idempotencia, incluyendo preguntas de examen y etiquetas.
En Pocas Palabras
Idempotencia significa: ejecutar la misma operación tantas veces como sea necesario con el mismo resultado. Formalmente: f(f(x)) = f(x).
Descripción Técnica Compacta
La idempotencia es una propiedad de la operación, no del endpoint. Hace que el resultado sea estable frente a repeticiones. En HTTP, GET, HEAD, PUT y DELETE son idempotentes según la especificación, POST no lo es, pero puede hacerse idempotente mediante Idempotency Key. En la práctica, idempotencia significa que las repeticiones no generan efectos secundarios adicionales (sin pedidos duplicados, sin cargos múltiples). Técnicamente se logra mediante transiciones de estado deterministas, verificaciones de versión con ETag y lógica de deduplicación en el servidor. En sistemas distribuidos con entrega al menos una vez, los reintentos son normales; la idempotencia los hace seguros.
Puntos Clave para el Examen
- Definición: f(f(x)) = f(x), idempotencia como propiedad de la operación, no de la ruta
- Mapeo HTTP: GET/HEAD segura e idempotente, PUT/DELETE idempotente, POST no idempotente
- Idempotencia en POST con Idempotency Key, hash de solicitud, almacén deduplicador, respuestas deterministas
- Estados y encabezados: 201 con Location en el primer intento, repetición devuelve 200/201 consistentemente, 412 en conflicto If-Match
- Trazabilidad de efectos secundarios, registro de ID de correlación, reglas de reintentos documentadas
- Sin datos sensibles en errores, protección contra reproducción mediante keys limitadas en tiempo y firmas
- Menos cargos duplicados y casos de soporte, integraciones robustas, política de reintentos claramente definida
- OpenAPI describe idempotencia, catálogo de errores, tiempo de vida de las Idempotency Keys, ejemplos de respuestas
Componentes Principales
- Definición formal y distinción de propiedades Safe
- Semántica de métodos en HTTP: GET, HEAD, PUT, PATCH, DELETE, POST
- Solicitudes condicionales con ETag, If-Match, If-None-Match
- Deduplicación: almacenamiento, mapeo de key a respuesta, con tiempo de expiración
- Transiciones de estado deterministas y detección de conflictos (409, 412)
- Generación de Idempotency Key: el cliente crea una clave estable por evento empresarial
- Patrón Outbox/Inbox para efectos secundarios confiables (eventos, pagos)
- Estrategia de reintentos: backoff exponencial, respetar 429 y Retry-After
- Observabilidad: ID de correlación, trazabilidad de operaciones idempotentes
- Procedimientos de prueba: pruebas de reintento, pruebas de caos, pruebas de concurrencia y race conditions
Ejemplo Práctico
// POST idempotente para pago con Idempotency Key y ETag
POST payments
Headers: Content-Type: application/json, Idempotency-Key: pay-123-abc
Body: { orderId: 42, amount: 59.98, method: "card" }
Lógica del servidor:
if exists DedupeStore[key: pay-123-abc]:
return storedResponse
else:
if PaymentAlreadyConfirmed(orderId: 42):
resp = { id: "P9001", status: "confirmed" }, code: 200
else:
create Payment(id: "P9001", status: "confirmed")
resp = { id: "P9001", status: "confirmed" }, code: 201, headers: ETag: W/"r77"
DedupeStore.save(key: pay-123-abc -> resp with ttl: 24h)
return resp
Reintento con la misma clave:
El cliente envía nuevamente POST con Idempotency Key, el servidor devuelve la misma respuesta, 201 en el primer intento, 200 en reintentos posteriores, nunca cargo duplicado.
Ventajas y Desventajas
Ventajas
- Reintentos seguros ante errores de red
- Protección contra cargos duplicados
- Modelado de errores más claro
- Integraciones más robustas
- Mejor experiencia del usuario
Desventajas
- Almacenamiento adicional y sobrecarga de gestión para deduplicación
- Lógica más compleja para efectos secundarios
- Necesidad de definir con precisión el tiempo de vida y semántica
- Posibles bloqueos o conflictos en concurrencia
Preguntas Típicas de Examen (con Respuesta Breve)
- ¿Diferencia entre Safe e Idempotente? Safe: sin cambio de estado en el servidor (GET), Idempotente: ejecución múltiple sin efectos secundarios adicionales (PUT/DELETE).
- ¿Cómo hacer operaciones POST idempotentes? Idempotency Key por evento empresarial, almacén de deduplicación con Key→Response, lógica determinista, códigos de estado consistentes, validez limitada.
- ¿ETag e If-Match en idempotencia? Protegen contra actualizaciones perdidas, actualización solo con versión conocida, si no, 412 Precondition Failed.
- ¿DELETE es realmente idempotente? Primer DELETE devuelve 200/204, DELETE posteriores pueden devolver 204/404, el estado del sistema permanece igual (recurso eliminado).
- ¿Códigos de estado típicos en idempotencia/reintentos? 200/201/204 en éxitos, 409 en conflictos empresariales, 412 en precondición incumplida, 429 en límites + Retry-After, 5xx para errores temporales del servidor.
- ¿Cómo definir el tiempo de vida de Idempotency Key? Empresarialmente hasta que el evento sea final, técnicamente como ventana de tiempo (ej. 24h), documentado en la API.
- ¿Riesgos sin idempotencia en sistemas distribuidos? Efectos secundarios duplicados (pagos duplicados), estados inconsistentes, correcciones manuales, costos de soporte más altos.
- ¿Idempotencia con Event Sourcing y Outbox? Escribir evento en Outbox (misma transacción), publicar de manera confiable, consumidor con Inbox para IDs de evento procesados, manejador idempotente.