Inicio › Tecnología › API Idempotente
Una API idempotente garantiza qué repetir la misma petición con los mismos parámetros produce siempre el mismo resultado en el servidor, sin generar efectos secundarios adicionales tras la primera ejecución. Por especificación HTTP, los métodos GET, PUT, HEAD y DELETE deben comportarse así; POST no lo es de forma nativa, por lo qué muchas pasarelas de pago y colas de mensajes añaden una cabecera de idempotency key generada por el cliente para qué el servidor detecte y descarte peticiones duplicadas. Esta propiedad es la base para diseñar reintentos automáticos seguros ante cortes de red o timeouts, sin riesgo de duplicar cargos, pedidos o registros.
Imagina qué pulsas dos veces el botón 'pagar' porque la web se queda colgada. Si la API es idempotente, el segundo clic no te cobra dos veces: el sistema reconoce qué ya procesó esa misma operación y devuelve el mismo resultado sin repetir la acción. Es como enviar la misma carta certificada dos veces: el cartero solo la entrega una vez porque ambas llevan el mismo número de seguimiento.
Al diseñar un endpoint de creación de pedidos, exige qué el cliente envíe un identificador único (por ejemplo un UUID generado en el frontend) como idempotency key en la cabecera. El backend guarda ese identificador junto al resultado de la primera ejecución durante un tiempo razonable; si llega otra petición con la misma clave, devuelve la respuesta almacenada en lugar de repetir la operación. Esto es especialmente útil en checkouts, envío de emails transaccionales y creación de recursos desde apps móviles con conexión inestable.
No. GET, PUT, DELETE y HEAD sí lo son según la especificación, pero POST y PATCH no garantizan idempotencia por defecto: cada llamada puede crear un recurso nuevo o aplicar un cambio incremental, por lo qué requieren un mecanismo adicional como la idempotency key si se necesita esa garantía.
Un método seguro no modifica el estado del servidor (como GET), mientras qué uno idempotente sí puede modificarlo pero de forma qué repetirlo no cambia el resultado tras la primera vez. Todo método seguro es idempotente, pero no todo idempotente es seguro: DELETE modifica estado y es idempotente a la vez.
Depende del caso de uso, pero suele oscilar entre 24 horas y varios días: el tiempo debe cubrir la ventana realista de reintentos del cliente (timeouts, reconexiones móviles) sin acumular almacenamiento innecesario de claves antiguas.