2025-03-13

Si estás diseñando o consumiendo APIs REST, es fundamental entender el concepto de idempotencia. Este principio garantiza que una solicitud puede ejecutarse múltiples veces sin causar efectos no deseados en el servidor.

En este artículo, explicaremos qué es idempotencia, cómo afecta a los verbos HTTP, y algunos errores comunes al implementarla.

 

¿Qué es la idempotencia?

 

La idempotencia es una propiedad de algunas operaciones que permite obtener el mismo resultado, sin importar cuántas veces se ejecuten.

Ejemplo correcto de una operación idempotente en la vida real:
Consultar tu saldo bancario:

• Si revisas tu saldo en una aplicación bancaria (GET /saldo), el valor devuelto será el mismo a menos que otra transacción externa lo cambie.
• Puedes hacer la misma consulta una y otra vez sin afectar el saldo.

 

Ejemplo de una operación NO idempotente:
???? Realizar una transferencia bancaria:

• Si envías un POST /transferencia para transferir $100 a otra cuenta, cada vez que envíes la solicitud se realizará una nueva transacción.
• Si se repite varias veces, se duplicarán los pagos.

En el contexto de APIs REST, una operación idempotente significa que si el cliente realiza la misma solicitud varias veces, el estado del servidor no cambiará después de la primera vez.

 

Idempotencia en los verbos HTTP

 

No todos los verbos HTTP son idempotentes. Aquí analizamos cómo se comportan en una API REST:

 

Método HTTP	Idempotente	Explicación
GET	✅ Sí	Obtener información no cambia el estado del servidor.
POST	❌ No	Puede crear múltiples recursos si se ejecuta varias veces.
PUT	✅ Sí	Sobrescribe completamente un recurso sin importar cuántas veces se llame.
PATCH	❌ No	Puede modificar parcialmente un recurso y generar diferentes estados si se ejecuta varias veces.
DELETE	✅ Sí	El recurso se elimina la primera vez; las siguientes veces no tienen efecto adicional.

 

3. Ejemplos prácticos de idempotencia

 

GET: Idempotente

El método GET solo recupera datos y no modifica el servidor.

Ejemplo: Obtener información de un usuario:

GET /usuarios/1 HTTP/1.1

✅ Si se ejecuta una vez o mil veces, la respuesta es la misma.

 

POST: No idempotente

El método POST crea nuevos recursos, por lo que repetir la solicitud puede generar datos duplicados.

Ejemplo: Crear un usuario nuevo:

POST /usuarios HTTP/1.1
Content-Type: application/json

{
  "nombre": "Carlos"
}

❌ Si ejecutamos esta solicitud 3 veces, crearemos 3 usuarios diferentes.

Solución: Para evitar duplicados, se puede usar un idempotency key (explicado más adelante).

 

PUT: Idempotente

El método PUT se usa para reemplazar completamente un recurso, por lo que ejecutar la misma solicitud varias veces no cambia el estado después de la primera vez.

Ejemplo: Modificar un usuario:

PUT /usuarios/1 HTTP/1.1
Content-Type: application/json

{
  "nombre": "Carlos Pérez",
  "email": "carlos@ejemplo.com"
}

✅ Si se ejecuta varias veces, el usuario seguirá teniendo los mismos datos.

 

PATCH: No idempotente

El método PATCH modifica parcialmente un recurso, por lo que si se ejecuta varias veces, podría generar cambios diferentes cada vez.

Ejemplo: Actualizar solo el nombre:

PATCH /usuarios/1 HTTP/1.1
Content-Type: application/json

{
  "nombre": "Carlos Pérez"
}

❌ Si se ejecuta varias veces con valores distintos, el estado final del recurso cambiará en cada llamada.

 

DELETE: Idempotente

El método DELETE elimina un recurso. La primera vez borra el dato, pero las siguientes llamadas no tendrán efecto adicional porque el recurso ya no existe.

Ejemplo: Eliminar un usuario:

DELETE /usuarios/1 HTTP/1.1

✅ Si el recurso ya está eliminado, la respuesta será 404 Not Found, pero el estado del servidor no cambia.

 

Cómo manejar la idempotencia en POST (Idempotency Keys)

 

En algunos casos, POST necesita ser idempotente, como cuando realizamos pagos en línea.

Para evitar pagos duplicados, se usa un Idempotency Key: un identificador único enviado en el encabezado que evita repetir la misma operación.

Ejemplo de solicitud con Idempotency Key:

POST /pagos HTTP/1.1
Content-Type: application/json
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

{
  "monto": 100,
  "moneda": "USD"
}

Comportamiento en el servidor:

1. Si la clave ya existe en el servidor, se devuelve la misma respuesta sin procesar un pago nuevo.
2. Si la clave es nueva, el servidor ejecuta la operación.

 

Últimas publicaciones