Batch (Beta)
La API Batch representa una evolución significativa en la funcionalidad de nuestra API Rest existente, ofreciendo un módulo integral diseñado para optimizar la ejecución de operaciones a través de la capacidad de procesamiento en paralelo. Este módulo permite a los usuarios consolidar múltiples solicitudes individuales en una única petición POST a /v1/batch, mejorando la eficiencia y reduciendo el tiempo de respuesta.

Funcionamiento General

  • Solicitud POST - /v1/batch

    El núcleo de la API Batch es la solicitud POST a /v1/batch. Aquí, el cuerpo de la solicitud sigue un formato estructurado que incluye un bloque webhook y un array de operations.
    • webhook: Este bloque permite al usuario ser notificado directamente sobre el estado del proceso batch, ya sea a través de una llamada a una URL especificada en callbackUrl o mediante el envío de un correo electrónico a la dirección proporcionada.
    • operations: El array operations contiene las operaciones a realizar, cada una con un identificador único (operationId), el endpoint que especifica el recurso (endpoint), el método HTTP (method), y opcionalmente, el cuerpo del mensaje (body) para las solicitudes POST o PUT.

  • Control de Puntos de Carga

    Para garantizar un uso eficiente de la API Batch, es fundamental tener en cuenta los puntos de carga asignados a cada recurso. La suma de los puntos de carga de todas las operaciones en el cuerpo de la solicitud no debe superar el máximo permitido. Los puntos de carga pueden variar con el tiempo, por lo que se recomienda utilizar el recurso GET - /v1/batch/limits para obtener información actualizada sobre los puntos de carga de cada recurso.

  • Estado y Seguimiento Concurrente

    La solicitud POST a /v1/batch es asincrónica, proporcionando rápidamente un identificador único de proceso (UUID). Para verificar el estado del proceso, se puede utilizar GET - /v1/batch/{uuid}, que proporciona detalles sobre si el proceso ha finalizado o está en curso, junto con información interna detallada de cada operación. Es importante destacar que el sistema controla la concurrencia y evita la ejecución simultánea de dos solicitudes batch. En caso de intentar lanzar una segunda solicitud mientras una está en proceso, el sistema informará al usuario mediante un código de error.

Recursos Adicionales

  • GET - /v1/batch/limits

    Este recurso brinda los puntos de carga asignados a cada recurso disponible en la API. La variabilidad en los puntos de carga a lo largo del tiempo se gestiona mediante esta consulta, permitiendo a los clientes adaptar sus estrategias de solicitudes en consecuencia.

Descarga de Respuestas

Una vez finalizado el proceso batch, dos recursos permiten la descarga de las respuestas: GET /v1/batch/{uuid}/jsonl: Descarga un archivo en formato JSONL (JSON Lines) que almacena las respuestas de todas las operaciones realizadas durante el proceso batch. GET /v1/batch/{uuid}/gz: Descarga un archivo comprimido que contiene las respuestas de todas las operaciones realizadas durante el proceso batch, en formato JSONL. La descompresión del archivo revela el contenido en su formato original.