El conector API REST genérica se puede registrar y probar hoy. Lo que está probado por pruebas es nuestro lado — armado de la solicitud, paginación, reanudación, reintento con espera y protección del token. El formato de su API es lo que verifica la prueba de conexión. Ejemplos sintéticos.
Leia antes: Como os dados fluem · Catálogo de conectores.
O que é#
Un conector para sistemas sem conector pronto: usted describe la API (URL base,
ruta que lista los registros, dónde está la lista en el JSON y cómo página) y
el Ingestia lee los registros según el cronograma y los carga como una tabla en
la capa Bronze. Las columnas se descubren en la primera lectura (nombres
normalizados a snake_case; objetos y listas se convierten en texto JSON).
Para qué sirve#
Traer datos de un sistema interno, de un proveedor nicho o de una API de socio al datalake, sin esperar un conector dedicado — y sin exportar hojas de cálculo manualmente.
Cuándo usar / cuándo no usar#
- Use cuando: la API responde JSON por HTTPS, lista registros en un endpoint (GET o POST) y pagina por número de página, por offset o por URL de la siguiente página en el cuerpo (o no pagina).
- No use cuando: el sistema tiene conector propio en el catálogo (prefiera ese — conoce el sobre y los límites de la API), la API exige OAuth con renovación de token, firma por solicitud o clave en un header propio (esas formas quedan para una evolución del conector), o la respuesta es XML/CSV.
Plano y permisos#
- 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: un token solo lectura, dedicado al Ingestia.
Pré-requisitos#
- La URL base de la API (comienza con
https://) y la ruta que lista los registros (ej.:/v1/pedidos). - Saber dónde está la lista en la respuesta: la respuesta ya es un array (
[...]), o el array está en una clave (data,results,data.items). - Saber cómo la API pagina y cuál es el tamaño máximo de página aceptado.
- Un token Bearer, si la API lo requiere (viaja como
Authorization: Bearer …; cifrado, nunca reexpuesto).
Paso a paso#
- En el console, vaya a Fontes › Conectores y elija API REST genérica (categoria APIs genéricas).
- Complete la descripción de la API:
- URL base — ej.:
https://api.exemplo.com - Caminho do recurso — ej.:
/v1/pedidos - Método HTTP —
GET(parámetros en la query) oPOST(en el cuerpo JSON) - Caminho da lista na resposta — ej.:
data(vacío = la respuesta ya es el array)
- URL base — ej.:
- En Paginação, elija el estilo de la API y complete lo que solicita:
- Nenhuma — una sola respuesta.
- Por número de página — parámetro de la página (ej.:
page), parámetro de tamaño (ej.:per_page) y el tamaño máximo que la API acepta. - Por deslocamento (offset) — parámetro de offset (ej.:
offset,skip), parámetro de tamaño (ej.:limit) y el tamaño máximo. - URL da próxima página no corpo — dónde la respuesta trae la siguiente URL
(ej.:
next,links.next,paging.next; acepta URL relativa).
- Si la API exige token, pégelo en Token Bearer. En Query extra, fije
parámetros que toda llamada debe llevar (ej.:
status=active&sort=desc). - Haga clic en Testar conexão. El Ingestia solicita una página pequeña, verifica que la lista existe en la ruta informada y muestra la tabla descubierta.
- Con la prueba OK, guarde la fuente e inclúyala en un pipeline. La tabla Bronze se
llama
registros.
Cómo funciona la lectura (y dónde se detiene)#
- Por página y por offset, la lectura se detiene en la primera página más corta que el tamaño pedido — por eso el campo solicita el máximo que la API acepta. Si la API ignora el tamaño y devuelve siempre menos, informe el tamaño que realmente devuelve.
- Por URL en el cuerpo, la lectura sigue la siguiente URL hasta que venga vacía o ausente. Una URL que se repite se trata como fin (no genera loop).
- Con token vacío, no se envía ningún header de autorización (APIs abiertas).
- Respuestas 429 y 5xx se reintentan con espera (y
Retry-Aftercuando exista). 401/403 interrumpen con el mensaje "credencial recusada" — el token nunca aparece en el error. - La extracción es completa en cada ejecución (sin ventana incremental). Fuentes muy grandes pueden necesitar una ruta más restrictiva o Query extra con filtro.
Problemas comunes#
| Sintoma | Causa provável | O que fazer |
|---|---|---|
"A resposta não tem uma lista em <caminho>" | caminho da lista errado | verifique el JSON de la API; use notación con punto (data.items) |
| Só a primeira página chega | parámetro de tamanho/página errado, ou tamanho maior que o aceito | ajuste los nombres de los parámetros y use el máximo real de la API |
| "Credencial recusada" | token inválido, expirado ou sem permissão | genere un token de lectura nuevo y actualice la fuente |
| Colunas com nomes estranhos | a API usa chaves com espaços/acentos | normal — normalizamos para snake_case; renombre en la camada Silver |
| Objetos aparecem como texto | campo aninhado | es el comportamiento esperado (JSON en texto); extraiga en la Silver |
Relacionados#
- Catálogo de conectores — estado y condición de cada conector.
- Criar pipeline full — de la fuente a la publicación.
- Status e limitações — lo que no prometemos hoy.