REST

La tarea REST en Gaio DataOS permite conectarse a cualquier API externa — pública o privada — directamente dentro de tu flujo de datos. Puedes utilizarla para obtener datos, enviar información, automatizar integraciones, convertir respuestas JSON en tablas dentro del proyecto e integrar IA, analítica y workflows con servicios externos.

---

Métodos HTTP soportados

La tarea REST soporta los siguientes métodos HTTP:

Método	Descripción
GET	Recuperar datos
POST	Enviar datos / crear recursos
PUT	Reemplazar recursos
PATCH	Actualizar recursos parcialmente
DELETE	Eliminar recursos

El comportamiento de PUT, PATCH y DELETE sigue la semántica estándar utilizada en arquitecturas REST.

---

Cómo usar la tarea REST

1. Abrir la tarea REST

En el Studio, ve al panel izquierdo: Tasks > ETL > REST

---

2. Elegir el método y configurar la URL

• Selecciona el método HTTP: GET, POST, PUT, DELETE, etc.

• En el campo URL, escribe el endpoint de la API.

• Puedes usar parámetros dinámicos:

• {{params.param_name}}
  {{table.table_name.column_name}}

  Example:

  https://api.example.com/users/{{user_id}}/posts?status={{status}}

Los parámetros se resuelven automáticamente en tiempo de ejecución.

---

3. Agregar parámetros

En la pestaña Parameters, puedes definir parámetros de URL:

• URL Parameter: Nombre del parámetro (ej.: userId).

• Value: Valor estático o dinámico (ej.: {{param.user_id}}).

Haz clic en + Add Parameter para agregar más.

---

4. Definir el cuerpo de la solicitud (Body)

En la pestaña Body, puedes:

• Escribir contenido JSON (principalmente para POST, PUT y PATCH).

• Usar variables dinámicas dentro del JSON.

Para las solicitudes POST, PUT y PATCH, puede definir un cuerpo de solicitud.

Ejemplo usando datos de tabla:

{
  "id": "{{ table.sales_rest.sale_id }}",
  "product": "{{ table.sales_rest.product }}"
}

Enviar todos los datos de la tabla en un solo lote

• Enabled: Envía la tabla completa en una sola solicitud.

• Disabled: Envía una solicitud por fila.

Útil para:

• Inserciones masivas

• Actualizaciones por lote

• Integraciones de alto rendimiento

---

5. Headers y autorización

• Headers: Permite agregar encabezados personalizados (Authorization, Content-Type, Accept, Bearer Token, etc.)

• Autorización: Configuración de Basic Auth.

---

6. Pestaña Result

Controla cómo la respuesta de la API se interpreta y convierte en tabla.

• Structure Identification: Detección automática de columnas y tipos (Automático por defecto).

• Object Property: Ruta hacia el array dentro del JSON (ej.: results.items).

• Always Drop Table: Reemplaza la tabla de resultados en cada ejecución.

• Input Columns to Keep: Selecciona qué columnas guardar.

• Object Property That Holds Results: Define qué propiedad contiene la lista de resultados.

Comportamiento

• Si la API devuelve un objeto JSON → se crea una fila.

• Si devuelve un array JSON → cada elemento se inserta como fila independiente.

---

7. Pestaña Error Log

Permite capturar errores durante la ejecución.

• Log Table: Nombre de la tabla que almacenará los errores (ej.: log_api_errors).

Facilita monitoreo y depuración en producción.

---

REST Task · Bulk Mode

El modo REST Bulk amplía la tarea REST estándar al permitir solicitudes API orientadas a lotes. En lugar de enviar una solicitud por fila, la tarea puede agregar datos de tablas y enviarlos en lotes a una API externa. Este modo es ideal para integraciones de gran volumen, inserciones masivas y flujos de trabajo API optimizados para el rendimiento.

Cuándo utilizar REST Bulk

Ideal para:

• APIs que soportan carga masiva

• Reducir cantidad de solicitudes HTTP

• Envío eficiente de grandes volúmenes

• Sincronización de tablas externas

Especialmente útil para POST, PUT y PATCH.

Configuración Bulk

Activar modo Bulk

Habilita Send all table data in a single batch.

Cuando está activado:

• Se envían múltiples filas juntas.

• El payload se construye desde la tabla fuente.

• Se optimiza el rendimiento.

---

Tamaño del lote (Batch Size)

Define cuántas filas enviar por solicitud:

• Número > 0 → filas por lote.

• 0 → envía toda la tabla en una sola solicitud.

---

Ejemplo de Body Bulk

{
  "data": {{ table.sales_rest }}
}

En este ejemplo:

• table.sales_rest se resuelve en una matriz de filas.

• Cada lote inyecta un subconjunto de la tabla.

• La API recibe una lista estructurada de registros.

La API recibirá:

{
  "data": [
    { ... },
    { ... }
  ]
}

Comportamiento en tiempo de ejecución (modo masivo)

Comportamiento en ejecución

• Lee la tabla fuente

• Divide según batch size

• Inserta cada lote en el body

• Envía una solicitud por lote

• Procesa respuesta

• Guarda resultados en tabla configurada

Relación con métodos HTTP

• POST → creación masiva

• PUT → reemplazo masivo

• PATCH → actualización masiva

• DELETE → eliminación masiva (según API)

El modo Bulk afecta cómo se envían los datos, no cómo se procesan los resultados.

Bulk at Root

El modo REST Bulk at Root es una variante de la configuración REST Bulk en la que los datos de la tabla se envían directamente en la raíz del cuerpo de la solicitud, en lugar de estar envueltos dentro de un objeto envolvente (como { data: [...] }).

Este modo está diseñado para API que esperan una matriz u objeto sin procesar en el nivel raíz de la carga útil de la solicitud.

Cuándo utilizar Bulk at Root

Utilice Bulk at Root cuando:

• La API espera una matriz JSON en la raíz.

• No se permite ninguna propiedad contenedora (por ejemplo, datos, elementos, carga útil).

• Se está integrando con API REST o de ingestión estrictas.

• La especificación de la API define explícitamente el cuerpo como una colección raíz.

Ejemplo esperado por API:

[
  { "id": 1, "product": "A" },
  { "id": 2, "product": "B" }
]

Diferencia clave con respecto al REST Bulk estándar

Modo	Estructura del Payload
REST Bulk	{ "data": [ ... ] }
REST Bulk at Root	[ ... ]

Body Payload (Root)

En Bulk at Root, el cuerpo solo contiene la referencia de la tabla, sin ningún contenedor.

Ejemplo de cuerpo:

{{ table.sales_rest }}

Bulk With Schema

El modo REST Bulk With Schema amplía REST Bulk al permitirle definir explícitamente la estructura de cada registro antes de enviar datos a una API externa.

En lugar de enviar filas de tabla sin procesar, se define una plantilla de esquema personalizada que controla:

• Qué campos se envían.

• Cómo se nombran los campos.

• Cómo se asignan las columnas de la tabla a la carga útil.

Este modo es ideal cuando las API requieren contratos de carga útil estrictos o asignaciones de campos personalizadas.

Cuándo utilizar Bulk con Schema

Ideal cuando:

• La API requiere estructura específica

• Los nombres de columnas no coinciden

• Se necesitan renombrar u omitir campos

• Se integra con APIs empresariales estrictas

Cómo funciona

Bulk With Schema introduce una definición de carga útil de dos capas:

1. Definición del esquema → cómo debe verse un registro individual.

2. Plantilla del cuerpo → cómo se agrupan y envían los registros.

El sistema genera el lote dinámicamente aplicando el esquema a cada fila.

Configuración de ejecución masiva

• Habilite la ejecución por lotes.

• Defina cuántas filas se envían por solicitud.

• Habilite «Definir el esquema de datos de la tabla».

Ejemplo de esquema:

{
  "id": "{{ table.sales_rest.sale_id }}",
  "product": "{{ table.sales_rest.product }}"
}

Esto significa:

• Cada fila de sales_rest se transforma en esta estructura.

• Los nombres de los campos se controlan explícitamente.

• Solo se envían los campos asignados.

El esquema se aplica por fila, incluso cuando se envían datos de forma masiva.

Modo	Estructura típica
REST Bulk	{ "data": {{ table }} }
REST Bulk at Root	{{ table }}
REST Bulk With Schema	{ "data": {{ schema }} }

Buenas prácticas

• Ejecuta siempre Run test antes de finalizar.

• Usa POST/PUT/PATCH para operaciones de modificación.

• Usa parámetros dinámicos para reutilizar la tarea.

• Usa modo Bulk en integraciones de alto volumen.

• Define correctamente la ruta en JSON anidado.

• Activa Error Log para monitoreo.

• Valida respuestas antes de procesos posteriores.