Ir al contenido principal
Explorar temas
API REST

Cómo evitar operaciones duplicadas en una API REST con Quarkus

Varias solicitudes POST con la misma clave de idempotencia convergen en una operación local y una respuesta basada en su resultado.
La clave de idempotencia permite reconocer reintentos y responder según el estado y el resultado de una operación anterior.

Cómo evitar operaciones duplicadas en una API REST con Quarkus

Una forma de reducir operaciones duplicadas en un POST es combinar una clave de idempotencia con una restricción única y una transacción para los cambios locales. El cliente usa la misma clave al reintentar una operación; el servidor la registra y decide si debe ejecutar el trabajo o responder a partir de una operación anterior.

Qué significa idempotencia en HTTP

Según la sección 9.2.2 de RFC 9110, la idempotencia se refiere al efecto previsto en el servidor: varias solicitudes idénticas tienen el mismo efecto previsto que una sola, aunque las respuestas puedan diferir. PUT, DELETE y los métodos seguros son idempotentes por su semántica HTTP; POST no tiene esa garantía general.

Definir el contrato de la clave

Como diseño para un POST, el cliente puede generar una clave por operación y conservarla para sus reintentos. El servidor puede asociar esa clave al ámbito del cliente, a una huella del contenido y al resultado necesario para responder después. La API debe explicar cómo compara el contenido, cuánto tiempo conserva la clave y qué ocurre después de su caducidad.

La revisión 08 del borrador IETF sobre Idempotency-Key, en sus secciones 2.1 y 2.2, indica que el valor de la cabecera “MUST be a String” de campo estructurado y que la clave “MUST NOT be reused” con otra carga. Su ejemplo muestra un UUID entre comillas. Son requisitos de esa revisión del borrador, no de un RFC publicado sobre esta cabecera.

En las secciones 2.3 a 2.5, el borrador permite usar una huella de la carga, recomienda definir y publicar una política de caducidad y exige publicar la especificación de idempotencia, incluida la caducidad cuando corresponda. El ámbito por cliente, la forma de calcular la huella y la conservación de una respuesta son decisiones del diseño de la API.

Respuestas ante reintentos y conflictos

Las secciones 2.6 y 2.7 del borrador recomiendan una respuesta coherente con la operación ya completada; no exigen reproducir literalmente la respuesta original. También recomiendan estos códigos:

  • 400: falta una clave exigida por la operación documentada.
  • 422: se reutiliza una clave con una carga diferente.
  • 409: la solicitud original sigue procesándose.

Estas respuestas son recomendaciones del borrador. El contrato concreto debe precisar qué estado, cuerpo y cabeceras se conservan, y cómo se recupera una operación que queda en curso.

Usar la base de datos para arbitrar solicitudes concurrentes

Consultar primero si existe una clave y después insertarla deja una carrera: dos solicitudes pueden observar que todavía no existe. Una opción de diseño es aplicar una restricción única a la combinación del ámbito del cliente y la clave.

En PostgreSQL, la cláusula ON CONFLICT de INSERT documenta que DO NOTHING evita la inserción ante un conflicto aplicable y que RETURNING devuelve las filas insertadas o actualizadas correctamente. La documentación también advierte de posibles bloqueos entre sesiones concurrentes y limita los árbitros a restricciones no diferibles e índices únicos. Esta sintaxis es específica de PostgreSQL.

La aplicación puede usar el resultado de la inserción para distinguir una clave nueva de un conflicto. Si hay conflicto, debe leer el registro existente y aplicar el contrato de comparación y respuesta. La visibilidad de esa lectura depende del aislamiento y del diseño transaccional; debe comprobarse en la implementación concreta.

Dos solicitudes concurrentes intentan registrar la misma combinación de cliente y clave; una restricción única impide crear dos registros.
La restricción única arbitra los intentos concurrentes; la espera y la lectura posterior dependen del aislamiento y del diseño transaccional.

Agrupar los cambios locales en Quarkus

Un método de un bean CDI anotado con @Transactional puede delimitar la transacción que registra la clave, aplica los cambios de negocio locales y guarda el resultado. Para que esta agrupación sea efectiva, todos esos cambios deben participar en la misma transacción.

La guía de transacciones de Quarkus indica que REQUIRED es el comportamiento predeterminado: inicia una transacción si no existe o se une a la existente. Por defecto, una RuntimeException que cruza el límite transaccional provoca rollback; rollbackOn y dontRollbackOn permiten modificar ese tratamiento y también se puede marcar la transacción para rollback.

Un flujo posible es el siguiente:

  1. Validar la clave y calcular una huella según las reglas publicadas por la API.
  2. Intentar insertar la combinación de ámbito y clave bajo una restricción única.
  3. Solo si esta solicitud inserta un registro nuevo, ejecutar la operación de negocio y guardar el resultado dentro de la misma transacción.
  4. Si la clave ya existe, leer el registro, comparar la huella y aplicar el contrato para una operación completada, en curso o con contenido distinto.

Este flujo es una recomendación de diseño, no una implementación verificada. En particular, no se ha establecido que un registro en curso sea visible ni que pueda devolverse un 409 sin esperar a otra transacción para un nivel de aislamiento concreto.

Cuándo aparecen los errores con Panache

La guía de Hibernate ORM con Panache explica que Hibernate suele enviar los cambios mediante un flush al final de la transacción o antes de una consulta. persistAndFlush adelanta ese envío y puede permitir detectar antes un error de persistencia, pero la transacción todavía debe confirmarse.

El estado de una transacción después de una excepción de persistencia debe verificarse para el proveedor y la implementación utilizados. No conviene asumir que capturar la excepción permite continuar con ella.

Considerar efectos externos y probar los fallos

Una transacción local no demuestra por sí sola que un pago, un mensaje o una llamada a otro servicio se ejecute exactamente una vez. Los fallos entre sistemas, la recuperación y la deduplicación del receptor requieren decisiones adicionales de arquitectura.

Una transacción local agrupa el registro de la clave, los cambios de negocio y el resultado, mientras los servicios externos quedan fuera de ese límite.
La transacción agrupa los cambios locales; los pagos, mensajes y llamadas externas requieren mecanismos adicionales de recuperación y deduplicación.

Antes de usar la solución, conviene probar solicitudes concurrentes con la misma clave, reintentos tras reinicios, reutilización con contenido distinto, caducidad y fallos de servicios externos. La investigación disponible no incluye una implementación ni pruebas que verifiquen esos casos; la retención, la canonicalización de la huella y las respuestas almacenadas dependen del contrato de cada API.

Comentarios

Buscar este blog