¿Qué significa una API idempotente?

Un endpoint de API idempotente produce el mismo resultado tanto si lo llamas una vez como diez, porque las peticiones idénticas repetidas no crean efectos duplicados. Es la propiedad que impide que un doble clic se convierta en un doble cargo.

El problema que resuelve es que las redes fallan a mitad de la petición. Si una llamada de pago expira, el cliente no puede saber si el servidor la procesó, así que reintenta. Sin idempotencia ese reintento podría cobrar la tarjeta dos veces, y con ella reintentar es siempre seguro. La implementación estándar es una clave de idempotencia: el cliente añade un identificador único a la petición, el servidor registra el resultado de la primera ejecución bajo esa clave, y cualquier repetición con la misma clave recibe la respuesta guardada en vez de ejecutarse otra vez. Algunos métodos HTTP son idempotentes por definición, ya que borrar algo dos veces lo deja igual de borrado, mientras que POST no lo es, y por eso las APIs de pago le acoplan claves. Cada aviso de "no pulses enviar dos veces" en una página de pago es un sistema admitiendo que se saltó esto.

El botón del ascensor. Púlsalo una vez o púlsalo siete veces suspirando, y viene un ascensor, porque la petición se registra una vez y cada repetición se asigna al mismo resultado. Un ascensor que enviara siete cabinas sería un endpoint de pago sin idempotencia.