Idempotencia

Para qué#

Si tu app no recibe respuesta a un POST, no sabe si llegó: ¿se aceptó el pedido?, ¿se creó la reserva? Sin protección, una repetición crea una segunda reserva. Con una Idempotency-Key, Flavoso responde a la repetición con el resultado del primer intento.

Cómo funciona#

• En un POST, envía la cabecera Idempotency-Key con una cadena única: de 1 a 255 caracteres ASCII imprimibles. En PUT, PATCH y DELETE, Flavoso ignora la cabecera.
• La clave se aplica por conexión. Flavoso conserva la primera respuesta (estado y cuerpo) durante 24 horas.
• Si la misma solicitud llega otra vez con la misma clave, se devuelve la primera respuesta, con Idempotent-Replayed: true, y no se ejecuta nada por segunda vez.
• Se comparan el método, la ruta y los bytes en bruto del cuerpo. Por eso, una repetición debe enviar exactamente el mismo cuerpo: basta con otros espacios u otro orden de los campos para que sea una solicitud distinta, y la misma clave con una solicitud distinta da 422 idempotency_key_reused.
• Si la primera solicitud sigue en curso, la segunda da 409 idempotency_in_progress. Espera un momento y repite. Si la primera nunca terminó (se interrumpió por nuestra parte), la clave queda libre de nuevo a los 2 minutos.
• Una respuesta con 5xx o 409 conflict no se conserva: la repetición se ejecuta.

# Create the key ONCE per operation and keep it for every retry of that operation
KEY=$(uuidgen)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $KEY"
# No answer? Send exactly the same command again, with the same $KEY.

HTTP/1.1 200 OK
Idempotent-Replayed: true
X-Request-Id: req_9a1b2c3d4e5f60718293a4b5
Content-Type: application/json

{ "object": "order", "id": "cce01f52-5188-410f-9659-6ce26ba9b784", "status": "confirmed", ... }

Buenas claves#

La clave pertenece a la operación, no al intento. Genérala una vez, cuando tu programa decida hacer algo, y úsala en cada repetición de esa misma operación.

• Derivada de tus propios datos: accept-<id del pedido>, ack-<id del pedido>, booking-<tu número de reserva>.
• O un UUID, guardado junto con la tarea en tu cola.
• Nunca una clave nueva en cada intento: así no protege de nada.

Lo que ya se puede repetir sin riesgo#

• Cambios de estado: un pedido que ya está en el estado de destino vuelve sin cambios con 200, y accept devuelve sin cambios un pedido que ya ha pasado de pending.
• POST /orders/{id}/acknowledge: un pedido del que ya te has hecho cargo sigue así; volver a enviar el mismo external_id no cambia nada.
• PUT /menu, PUT /store/hours, POST /menu/availability y cualquier PATCH: establecen un estado de destino, no lo alternan. Enviarlos dos veces tiene el mismo efecto que una.

En un POST, una Idempotency-Key nunca sobra y además garantiza la misma respuesta; en PUT y PATCH, Flavoso la ignora.