Idempotencia en el Diseño de APIs: Webhooks y Ejemplos Prácticos
La idempotencia garantiza que las llamadas repetidas a una API devuelvan el mismo resultado, algo crucial para pagos, pedidos y webhooks.
Descripción General
La idempotencia es una propiedad de las operaciones que pueden ejecutarse múltiples veces sin alterar el resultado. En el diseño de APIs, es fundamental para interfaces confiables y tolerantes a fallos. GET, PUT y DELETE son idempotentes, mientras que POST generalmente no lo es. Para operaciones no idempotentes como POST o llamadas externas como webhooks, se utilizan Idempotency Keys para evitar ejecuciones duplicadas. Los webhooks también deben diseñarse de manera idempotente, permitiendo que los receptores procesen el mismo evento varias veces sin duplicar datos. Una estrategia sólida de idempotencia reduce errores causados por problemas de red, reintentos y race conditions, mejorando significativamente la confiabilidad de las APIs.
Componentes Clave
Métodos HTTP Idempotentes
GET es idempotente porque no causa cambios de estado. PUT es idempotente porque reemplaza completamente un recurso, sin importar cuántas veces se ejecute. DELETE es idempotente porque después de la primera eliminación el recurso ya no existe y los intentos posteriores producen el mismo estado final. POST no es idempotente porque cada llamada puede crear un nuevo recurso.
Idempotency Keys
Una Idempotency Key es un valor único que el cliente envía con la solicitud. El servidor almacena la clave y el resultado de la primera solicitud. Cuando se recibe una llamada repetida con la misma clave, el servidor devuelve el resultado almacenado en lugar de ejecutar la operación nuevamente. Esto es especialmente importante para pagos, reservas y pedidos.
Garantía de Idempotencia en Pagos
En APIs de pago, un error de red puede causar que el cliente reintente la solicitud. Sin una Idempotency Key, el pago se ejecutaría potencialmente dos veces. Con la Idempotency Key, el servidor garantiza que el pago se procese una sola vez, incluso si el cliente realiza múltiples solicitudes.
Webhooks e Idempotencia
Los webhooks son eventos enviados por el servidor al cliente. Pueden llegar múltiples veces debido a timeouts o reintentos. El receptor debe procesar los webhooks de forma idempotente, identificando cada evento mediante un ID único y descartando o ignorando duplicados.
Estrategias de Reintento e Idempotencia
Los clientes solo deben reintentar operaciones idempotentes automáticamente. GET y PUT pueden reintentarse con seguridad ante errores de red. POST solo debe reintentarse si se usa una Idempotency Key. Sin ella, pueden ocurrir cargos duplicados no deseados.
Almacenamiento de Idempotency Keys
Las Idempotency Keys deben almacenarse en el servidor durante un período definido. El almacenamiento puede ser una base de datos, caché o servicio dedicado. Lo importante es que las claves se vinculen con el resultado de la operación y no puedan reutilizarse para solicitudes diferentes.
TTL y Retención
Las Idempotency Keys deben tener un tiempo de vida definido. Después de que expire el TTL, la clave puede eliminarse. El cliente debe conocer cuánto tiempo es válida una clave para evitar reutilizarla demasiado tarde. Los TTLs típicos oscilan entre minutos y días.
Evitar Race Conditions
Cuando dos solicitudes con la misma Idempotency Key llegan simultáneamente, el servidor debe garantizar que solo se ejecute una operación. Los mecanismos de bloqueo u operaciones atómicas de base de datos ayudan a evitar race conditions.
Manejo de Errores en Idempotency Keys
Si una Idempotency Key es inválida o ha expirado, la API debe devolver un mensaje de error claro. El cliente puede entonces decidir si ejecutar la operación con una nueva clave o reenviar la solicitud original.
Monitoreo y Logs
Las Idempotency Keys y las solicitudes repetidas deben registrarse. Esto facilita la depuración y permite identificar patrones como timeouts frecuentes o envíos duplicados. El monitoreo puede alertar sobre problemas con anticipación.
Ejemplo Práctico
Una tienda en línea ofrece una API para crear pedidos. El cliente quiere asegurar que un pedido no se cree accidentalmente dos veces.
Solicitud con Idempotency Key:
POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{
"customerId": 123,
"items": [
{ "productId": 42, "quantity": 2 }
]
}Primera ejecución:
HTTP/1.1 201 Created
Location: /api/v1/orders/98765
{
"orderId": 98765,
"status": "created",
"total": 79.97
}Solicitud repetida con la misma clave:
POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{
"customerId": 123,
"items": [
{ "productId": 42, "quantity": 2 }
]
}El servidor reconoce la clave y devuelve el mismo resultado:
HTTP/1.1 201 Created
Location: /api/v1/orders/98765
{
"orderId": 98765,
"status": "created",
"total": 79.97
}Webhook con Event-ID:
POST /webhooks/orders
Content-Type: application/json
X-Event-ID: event-12345-abcde
{
"eventType": "order.created",
"orderId": 98765,
"status": "created"
}El receptor almacena el X-Event-ID y procesa los IDs iguales solo una vez. De esta forma, el procesamiento permanece idempotente aunque el webhook se envíe múltiples veces.
Preguntas Frecuentes: Idempotencia en el Diseño de APIs
1. ¿Qué es Idempotencia?
2. ¿Qué métodos HTTP son idempotentes?
3. ¿Qué es una Idempotency Key?
4. ¿Por qué es importante la Idempotencia en pagos?
5. ¿Qué es un Webhook?
6. ¿Por qué los Webhooks deben ser idempotentes?
7. ¿Cómo se identifican Webhooks duplicados?
8. ¿Qué sucede con solicitudes simultáneas usando la misma Idempotency Key?
9. ¿Cuánto tiempo debe almacenarse una Idempotency Key?
10. ¿Puede PATCH ser idempotente?
11. ¿Qué ocurre con una Idempotency Key inválida?
12. ¿Se deben usar Idempotency Keys en todas las solicitudes POST?
13. ¿Cuál es la diferencia entre Idempotencia y Safe Methods?
14. ¿Cómo se prueba la Idempotencia?
15. ¿Qué relación existe entre Idempotencia y Estrategias de Reintento?
Continuando en la ruta de aprendizaje de API
El siguiente artículo en la ruta de aprendizaje de API cubre Fundamentos de Webhooks — cómo funcionan los webhooks, cómo implementarlos de forma segura y qué aspectos debes tener en cuenta en la verificación de firmas.
Referencias
- https://www.rfc-editor.org/rfc/rfc9110
- https://stripe.com/docs/api/idempotent_requests
- https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key
Lecturas recomendadas sobre desarrollo de APIs
Si deseas profundizar en idempotencia, diseño de APIs y arquitectura de software, te recomendamos los siguientes libros:
Keine Bücher für Kategorie "api-development" gefunden.