> 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-portuguese/tools/tarefas/etl/rest.md).

# REST

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

A **REST Task** no **Gaio DataOS** permite conectar-se a qualquer API externa — pública ou privada — diretamente dentro do seu fluxo de dados. Ela pode ser utilizada para buscar dados, enviar informações, automatizar integrações via API, converter respostas JSON em tabelas utilizáveis no projeto e integrar IA, analytics e workflows com serviços externos.

***

## Métodos HTTP suportados

A REST Task suporta os seguintes métodos HTTP:

| Metódo |                                 |
| ------ | ------------------------------- |
| GET    | Obter dados                     |
| POST   | Enviar dados/Criar recursos     |
| PUT    | Substituir recursos             |
| PATCH  | Parcialmente atualizar recursos |
| DELETE | Remover recursos                |

{% hint style="info" %}
O comportamento de **PUT**, **PATCH** e **DELETE** segue a semântica padrão utilizada em APIs REST.
{% endhint %}

## Como usar a REST&#x20;

### 1. Abrir a REST&#x20;

No **Studio**, acesse o painel **Tasks**.\
Na seção **ETL**, selecione **REST**.

***

### 2. Escolher o método e configurar a URL

* Selecione o método HTTP: **GET**, **POST**, **PUT**, **DELETE**, etc.
* No campo **URL**, informe o endpoint da API.

É possível utilizar **parâmetros dinâmicos** na URL:

```json
{{ params.param_name }}
{{ table.table_name.column_name }}
```

**Exemplo:**

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

{% hint style="info" %}
Os parâmetros da URL são resolvidos automaticamente em tempo de execução.
{% endhint %}

### 3. Adicionar parâmetros

Na aba **Parâmetros**, defina parâmetros de URL:

* **URL Parâmetro:** Nome do parâmetro (ex.: `userId`)
* **Valor:** Valor estático ou dinâmico (ex.: `{{ param.user_id }}`)

Clique em **+ Adicionar Parâmetro** para adicionar novos parâmetros.

***

### 4. Definir o corpo da requisição (Body), se necessário

Na aba **Corpo**, você pode:

* Inserir conteúdo **JSON** para o corpo da requisição (principalmente em **POST** e **PUT**)
* Utilizar variáveis dinâmicas dentro do conteúdo

{% hint style="info" %}
Para requisições do tipo **POST**,**PUT** e **PATCH,** você pode definir o corpo
{% endhint %}

**Exemplo de corpo usando dados de uma tabela:**

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

```

### **Enviar todos os dados da tabela em lote**

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

* **Habilitar:** envia toda a tabela em uma única requisição
* **Desabilitar:** envia uma requisição por linha

Isso é útil para:

* Inserções em massa
* Atualizações em lote
* Integrações de alta performance

***

### 5. Headers e autorização

* **Cabeçalhos:** adicione headers customizados como `Authorization`, `Content-Type`, `Accept`, Bearer Tokens, etc.
* **Autorizações:** configure autenticação **Basic Auth**, quando necessário.

***

### 6. Aba Resultado

Controla como a resposta da API será interpretada e convertida em tabela.

* **Identificação da estrutura:** Permite que o Gaio detecte automaticamente nomes de colunas e tipos de dados (padrão: *Automatic*).
* **Propriedade do objeto:** Define o caminho até o array dentro do JSON de resposta, caso seja aninhado (ex.: `results.items`).
* **Sempre excluir tabela:** Se habilitado, a tabela de resultado existente será substituída a cada execução.
* **Colunas de entrada para manter:** Seleciona quais colunas da resposta devem ser armazenadas.
* **Propriedade do objeto que contém os resultados retornados:** Define a propriedade JSON que contém a lista de resultados.

**Comportamento:**

* Se a API retornar um objeto JSON → uma linha será criada
* Se retornar um array JSON → cada item será inserido como uma linha separada

***

#### 7. Aba Error Log

Permite capturar e armazenar erros ocorridos durante a execução.

* **Tabela de log:** Nome da tabela que receberá os logs de erro da REST.\
  (ex.: `log_api_errors`)

Facilita depuração e monitoramento em ambientes produtivos.

<figure><img src="/files/73HDDzl2KLeUkTi44kfz" alt=""><figcaption></figcaption></figure>

## REST Task · Bulk Mode

O **REST Bulk Mode** estende a REST Task padrão, permitindo requisições orientadas a lote.\
Em vez de enviar uma requisição por linha, os dados da tabela são agregados e enviados em blocos para a API externa. Ideal para **integrações de alto volume**, **inserções em massa** e fluxos otimizados para performance.

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

### Quando usar REST Bulk

Use REST Bulk quando:

* A API suporta payloads em lote
* Você deseja reduzir o número de requisições HTTP
* Precisa enviar grandes volumes de dados de forma eficiente
* Está sincronizando tabelas com sistemas externos

{% hint style="info" %}
Especialmente indicado para **POST**, **PUT** e **PATCH**.
{% endhint %}

#### Configuração do Bulk

As configurações de bulk ficam na aba **Body** e incluem:

* Controle de execução em lote
* Paginação sobre os dados da tabela
* Definição opcional de schema para o payload

***

#### Habilitar Bulk Mode

Ative **Send all table data in a single batch**.

Quando habilitado:

* A REST Task envia múltiplas linhas juntas
* O payload é construído a partir da tabela de origem
* A execução é otimizada para maior throughput

***

#### Batch Size (Paginação da tabela)

Define quantas linhas são enviadas por requisição:

* Valor numérico: número de linhas por lote
* **0:** carrega e envia a tabela inteira em uma única requisição

***

#### Body Payload (Bulk)

O editor de **Body** define como os dados em lote são enviados.

**Exemplo:**

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

Neste caso:

* `table.sales_rest` é resolvido como um array de linhas
* Cada lote injeta um subconjunto da tabela
* A API recebe uma lista estruturada de registros

Padrão comum para APIs que esperam:

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

***

#### Comportamento em tempo de execução (Bulk)

Durante a execução:

1. A task lê a tabela de origem
2. Divide os dados conforme o tamanho do lote
3. Injeta cada lote no body da requisição
4. Envia uma requisição por lote
5. Processa as respostas da API
6. Grava os resultados na tabela configurada

***

#### Relação com métodos HTTP

* **POST:** criação em lote
* **PUT:** substituição em lote
* **PATCH:** atualização em lote
* **DELETE:** exclusão em lote (dependente da API)

{% hint style="info" %}
O modo bulk altera apenas a forma de envio dos dados, não o parsing da resposta.
{% endhint %}

### REST Bulk at Root

O **REST Bulk at Root** é uma variação do modo Bulk onde os dados da tabela são enviados diretamente na raiz do body da requisição, sem um wrapper (como `{ data: [...] }`).

***

#### Quando usar Bulk at Root

Use quando:

* A API espera um array JSON na raiz
* Nenhuma propriedade intermediária é permitida
* A API é estrita quanto ao formato do payload

**Exemplo esperado pela API:**

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

**Exemplo de Body (Bulk at Root):**

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

### REST Bulk With Schema

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

O **REST Bulk With Schema** permite definir explicitamente a estrutura de cada registro antes do envio à API externa.

Em vez de enviar linhas brutas da tabela, você define um schema customizado que controla:

* Quais campos são enviados
* Como os campos são nomeados
* Como as colunas da tabela são mapeadas no payload

Ideal para APIs com contratos rígidos.

***

#### Quando usar Bulk With Schema

Use quando:

* A API exige uma **estrutura JSON específica**
* Os nomes das colunas não coincidem com os nomes esperados pela API
* É necessário omitir ou renomear campos
* Você precisa de controle total sobre o payload

***

#### Como funciona o Bulk With Schema

Esse modo introduz **duas camadas**:

* **Schema:** define a estrutura de um único registro
* **Body template:** define como os registros são agrupados e enviados

O sistema aplica o schema dinamicamente a cada linha.

**Exemplo de schema:**

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

Isso significa que:

* Cada linha de `sales_rest` é transformada nesse formato
* Apenas os campos mapeados são enviados

{% hint style="info" %}
O schema é aplicado linha a linha, mesmo em modo bulk
{% endhint %}

| Modo                 | Estrutura típica           |
| -------------------- | -------------------------- |
| Rest Bulk            | `{ "data": {{ table }} }`  |
| Rest Bulk at Root    | `{{ table }}`              |
| Rest Bul With Schema | `{ "data": {{ schema }} }` |

***

### Boas práticas

* Sempre utilize **Executar teste** antes de finalizar a configuração
* Use **POST / PUT / PATCH** para operações de mutação
* Utilize parâmetros dinâmicos para reaproveitar a mesma task
* Use **batch mode** para APIs de alto volume
* Em JSONs aninhados, defina corretamente o **Object Property**
* Ative a aba **Error Log** para rastrear falhas
* Valide as respostas da API antes de usá-las em etapas posteriores