> For the complete documentation index, see [llms.txt](https://docs.gaiodataos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaiodataos.com/gaio-dataos-spanish/herramientas/tareas/etl/rest.md).

# REST

<figure><img src="/files/vbInGz4RoQOr03Blj1ax" alt=""><figcaption></figcaption></figure>

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                |

{% hint style="info" %}
El comportamiento de **PUT, PATCH y DELETE** sigue la semántica estándar utilizada en arquitecturas REST.
{% endhint %}

***

## &#x20;

## 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:
* ```plaintext
  {{params.param_name}}
  {{table.table_name.column_name}}
  ```

  **Example**:

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

{% hint style="info" %}
Los parámetros se resuelven **automáticamente en tiempo de ejecución.**
{% endhint %}

***

### 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.

{% hint style="info" %}
Para las solicitudes **POST, PUT y PATCH,** puede definir un **cuerpo de solicitud.**
{% endhint %}

Ejemplo usando datos de tabla:

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

```

#### Enviar todos los datos de la tabla en un solo lote

<figure><img src="/files/cEkfeaTxL3pRz4Z9Vzgm" alt=""><figcaption></figcaption></figure>

* **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.

<figure><img src="/files/qarq0xxEXS4o2ZCkxWAm" alt=""><figcaption></figcaption></figure>

***

## 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.

<figure><img src="/files/ZIMLUtPKgOpVFK1iMsTS" alt=""><figcaption></figcaption></figure>

### 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

{% hint style="info" %}
Especialmente útil para POST, PUT y PATCH.
{% endhint %}

### 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

```json
{
  "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á:

```json
{
  "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)

{% hint style="info" %}
El modo Bulk afecta cómo se envían los datos, no cómo se procesan los resultados.
{% endhint %}

### 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:**

```json
[
  { "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:**

```json
{{ table.sales_rest }}
```

## Bulk With Schema

<figure><img src="/files/6PHWlpeOvw4CSlccTxb7" alt=""><figcaption></figcaption></figure>

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.

{% hint style="info" %}
Este modo es ideal cuando las API requieren contratos de carga útil estrictos o asignaciones de campos personalizadas.
{% endhint %}

### 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:**

```json
{
  "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.

{% hint style="info" %}
El esquema se aplica **por fila**, incluso cuando se envían datos de forma masiva.
{% endhint %}

| 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.