Ir al contenido
Quiet Social

Idempotencia

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

El riesgo central de una API de publicación es publicar dos veces. Un cliente HTTP que pierde la respuesta a un POST lo reintentará y, sin protección, el segundo intento crearía una segunda publicación. Por eso la API exige una clave de idempotencia en las escrituras que crean algo.

Dónde se exige la clave

La cabecera Idempotency-Key es obligatoria en:

  • POST /publications;
  • POST /media.

Sin ella, la petición se rechaza antes de cualquier ejecución:

{
  "error": {
    "code": "idempotency_key_required",
    "message": "L'en-tête Idempotency-Key est obligatoire sur cette écriture : sans lui, une requête rejouée après un délai réseau publierait une seconde fois."
  }
}

Una clave de más de 255 caracteres recibe 400 idempotency_key_too_long.

Elegir una clave

Deriva la clave de lo que desencadena la escritura, en lugar de generarla al azar: article-42-publie-v1 se vuelve a calcular idéntica tras un reinicio de tu proceso; un UUID generado sobre la marcha no se recupera.

Si tu clave natural es larga — una URL, una ruta —, aplícale un hash: 'pub-'.hash('sha256', $url) cabe en 68 caracteres y sigue siendo determinista.

Una clave nunca se comparte entre dos clientes de API: el mismo valor empleado por dos clientes designa dos peticiones distintas.

Lo que ocurre a la recepción

Situación Respuesta
Clave desconocida La petición se ejecuta. Si tiene éxito, su respuesta se conserva.
Clave conocida, mismo cuerpo, respuesta conservada La respuesta conservada se devuelve tal cual, con la cabecera Idempotent-Replay: true. No se vuelve a crear nada.
Clave conocida, mismo cuerpo, petición aún en curso 409 idempotency_key_in_flight.
Clave conocida, cuerpo diferente 409 idempotency_key_reused.

Devolver el recurso original ante un cuerpo diferente haría creer al cliente que su nueva solicitud se ha tenido en cuenta: por eso este caso es un conflicto.

Detalles del mecanismo

  • Solo se conservan los éxitos. Una respuesta de error (estado 400 o superior) libera la clave: la petición puede corregirse y repetirse con la misma clave.
  • La clave se reserva antes de la ejecución. Dos peticiones concurrentes con la misma clave no pueden ejecutarse ambas; la segunda recibe 409 idempotency_key_in_flight.
  • Una reserva abandonada se recupera. Si el proceso que tenía la clave se detuvo sin responder, la reserva se da por perdida al cabo de cinco minutos, y la siguiente petición con esa clave se ejecuta con normalidad.
  • Una clave vive 24 horas. Pasado ese plazo, se olvida: el mismo valor vuelve a ser una clave desconocida. No cuentes con una clave de más de un día para impedir un duplicado.
  • La huella del cuerpo ignora el orden de las claves de un objeto, en todos los niveles: {"a":1,"b":2} y {"b":2,"a":1} son el mismo cuerpo. Las listas, en cambio, conservan su orden: destination_ids en otro orden es otro cuerpo.
  • En un envío de archivo, la huella se calcula sobre el contenido (resumen SHA-256), no sobre el nombre: volver a enviar la misma imagen con otro nombre es el mismo envío.

Las demás escrituras

Las transiciones — publish, cancel, retry — se llaman sin clave. Son idempotentes por naturaleza: cada una rechaza el estado que produce, y una segunda llamada responde 409 transition_not_allowed sin cambiar nada.

Las escrituras de webhook tampoco la exigen: declarar dos veces el mismo endpoint se ve y se corrige, mientras que publicar dos veces no tiene arreglo.

Reintentar sin publicar dos veces

La regla cabe en una línea: conserva la clave, repite la petición.

Situación Clave Cuerpo
Red cortada, ninguna respuesta la misma sin cambios
5xx la misma sin cambios
429 la misma sin cambios
409 idempotency_key_in_flight la misma, tras un breve plazo sin cambios
422 la misma corregido
400 sobre la clave corregida sin cambios
Contenido deliberadamente diferente nueva nuevo

Una repetición que devuelve la respuesta conservada lleva Idempotent-Replay: true: esta vez no se ha creado nada, lo que evita contar dos veces la misma publicación en tus propias estadísticas.