Tutorial — conectar uma API REST genérica

Estado: o conector API REST genérica está em Acesso limitado (maturidade Preview): dá para cadastrar e testar hoje, e a liberação geral depende de validação com APIs reais de clientes e de 30 dias de execução controlada. O que está provado por teste é o nosso lado — montagem da requisição, paginação, retomada, repetição com espera e proteção do token. O formato da sua API é o que o teste de conexão confere. Como todo o produto, ainda sem SLA público. Exemplos sintéticos.

Leia antes: Como os dados fluem · Catálogo de conectores.

O que é#

Um conector para sistemas sem conector pronto: você descreve a API (URL base, caminho que lista os registros, onde está a lista no JSON e como ela pagina) e o Ingestia lê os registros no agendamento e os carrega como uma tabela na camada Bronze. As colunas são descobertas na primeira leitura (nomes normalizados para snake_case; objetos e listas viram texto JSON).

Para que serve#

Trazer dados de um sistema interno, de um fornecedor de nicho ou de uma API de parceiro para o datalake, sem esperar um conector dedicado — e sem exportar planilhas à mão.

Quando usar / quando não usar#

• Use quando: a API responde JSON por HTTPS, lista registros num endpoint (GET ou POST) e pagina por número de página, por offset ou por URL da próxima página no corpo (ou não pagina).
• Não use quando: o sistema tem conector próprio no catálogo (prefira-o — ele conhece o envelope e os limites da API), a API exige OAuth com renovação de token, assinatura por requisição ou chave num header próprio (essas formas ficam para uma evolução do conector), ou a resposta é XML/CSV.

Plano e permissões#

• Núcleo do produto · verificação de acesso (workspace ativo).
• A carga passa pela chave de desligamento da capacidade execução de ingestão.
• Recomendado: um token somente leitura, dedicado ao Ingestia.

Pré-requisitos#

1. A URL base da API (começa com https://) e o caminho que lista os registros (ex.: /v1/pedidos).
2. Saber onde fica a lista na resposta: a resposta já é um array ([...]), ou o array está numa chave (data, results, data.items).
3. Saber como a API pagina e qual o tamanho máximo de página aceito.
4. Um token Bearer, se a API exigir (viaja como Authorization: Bearer …; cifrado, nunca reexibido).

Passo a passo#

1. No console, vá em Fontes › Conectores e escolha API REST genérica (categoria APIs genéricas).
2. Preencha a descrição da API:
   • URL base — ex.: https://api.exemplo.com
   • Caminho do recurso — ex.: /v1/pedidos
   • Método HTTP — GET (parâmetros na query) ou POST (no corpo JSON)
   • Caminho da lista na resposta — ex.: data (vazio = a resposta já é o array)
3. Em Paginação, escolha o estilo da API e preencha o que ele pede:
   • Nenhuma — uma resposta só.
   • Por número de página — parâmetro da página (ex.: page), parâmetro de tamanho (ex.: per_page) e o tamanho máximo que a API aceita.
   • Por deslocamento (offset) — parâmetro de offset (ex.: offset, skip), parâmetro de tamanho (ex.: limit) e o tamanho máximo.
   • URL da próxima página no corpo — onde a resposta traz a próxima URL (ex.: next, links.next, paging.next; aceita URL relativa).
4. Se a API exigir token, cole-o em Token Bearer. Em Query extra, fixe parâmetros que toda chamada deve levar (ex.: status=active&sort=desc).
5. Clique em Testar conexão. O Ingestia pede uma página pequena, confere que a lista existe no caminho informado e mostra a tabela descoberta.
6. Com o teste OK, salve a fonte e inclua-a num pipeline. A tabela Bronze se chama registros.

Como a leitura funciona (e onde ela para)#

• Por página e por offset, a leitura para na primeira página mais curta que o tamanho pedido — por isso o campo pede o máximo que a API aceita. Se a API ignorar o tamanho e devolver sempre menos, informe o tamanho que ela realmente devolve.
• Por URL no corpo, a leitura segue a próxima URL até ela vir vazia ou ausente. Uma URL que se repete é tratada como fim (não vira loop).
• Com token vazio, nenhum header de autorização é enviado (APIs abertas).
• Respostas 429 e 5xx são repetidas com espera (e Retry-After quando houver). 401/403 interrompem com a mensagem "credencial recusada" — o token nunca aparece no erro.
• A extração é completa a cada execução (sem janela incremental). Fontes muito grandes podem precisar de um caminho mais restrito ou de Query extra com filtro.

Problemas comuns#

Relacionados#

• Catálogo de conectores — estado e condição de cada conector.
• Criar pipeline full — da fonte à publicação.
• Status e limitações — o que não prometemos hoje.