# Conector de API customizado: qualquer API direto do GitHub > Descreva qualquer API REST ou GraphQL em YAML, faça push no GitHub e a Erathos transforma em um conector monitorado. Source: https://www.erathos.com/blog/conector-api-customizado-como-codigo Published: 2026-10-07 Category: Novidades da Plataforma ![Conector de API customizado: qualquer API direto do GitHub](https://cms-media.erathos.com/Custom connector PT.png) Provavelmente existe, em algum lugar da sua stack, um script Python que se conecta a alguma API que nenhuma ferramenta de ingestão do mercado suporta: a API interna de pedidos da sua empresa, uma ferramenta SaaS de nicho que o time de vendas adora ou algum sistema regional sem conector em nenhum catálogo. Esse script roda em algum cron job ou cloud function, até o dia em que para de rodar. Com o Custom Connector da Erathos, você escreve alguns arquivos YAML no seu próprio repositório do GitHub para descrever a API e depois faz push para o seu repositório. A Erathos então executa o seu Custom Connector como se fosse qualquer outro conector. [Crie um conector customizado para qualquer API com Erathos + GitHub](https://youtu.be/dXFD3P8d68M?si=k6XDdYJLynJVpa3j) ## O script caseiro que ninguém quer manter Scripts caseiros de API costumam sofrer com vários problemas: - **Sem retentativas**. Uma única requisição com falha (como um timeout ou rate limit) interrompe o script por completo, o que significa que você vai ficar um dia atrasado nas atualizações até alguém perceber. - **Sem alertas**. Se o script falhar, ninguém será notificado. Você só vai descobrir quando algo parecer errado em um dashboard. - **Credenciais embutidas no script**. Sua chave de API vai estar hardcoded no script ou em um arquivo de configuração ao lado dele. - **Sem rastreabilidade**. Não há como saber qual execução do script carregou quais linhas, nem quando um determinado registro foi atualizado pela última vez. - **Sem resiliência a mudanças na API**. Se a API mudar (talvez um campo seja renomeado ou o estilo de paginação mude), você vai ter que voltar a mexer em um script que não toca há meses. - **Ponto único de falha**. Só uma pessoa vai saber como rodar ou modificar o script; então, se ela estiver de férias ou sair da empresa, você está em apuros. Cada nova API geralmente significa um script totalmente novo, o que significa reimplementar paginação, retentativas e controle de rate limit toda vez. ## O que é um Custom Connector da Erathos? Um Custom Connector da Erathos é um conector que você descreve em arquivos YAML declarativos, armazenados no seu próprio repositório do GitHub, sem precisar escrever nenhuma linha de código Python. A Erathos então [monitora o repositório e reconstrói o conector a cada push](https://docs.erathos.com/connectors/custom-connectors). Depois que o build inicial é concluído, seu conector fica disponível no catálogo de fontes de dados, com um selo **Custom**, e pode ser conectado exatamente da mesma forma que um conector nativo. Você escolhe os endpoints, o agendamento e o tipo de sincronização, e os dados são enviados para o seu warehouse. O YAML define três coisas: onde ficam os dados da API, como paginar por eles e os nomes dos campos. A Erathos cuida da execução, das retentativas e de manter o histórico de execuções. Nas palavras do [repositório template](https://github.com/erathos-data/custom-api-connector): "Você não vai escrever nenhuma linha de Python." ## Como a notação YAML descreve uma API _Plano: percorrer o \_default.yml, um arquivo de endpoint, os campos e os três tipos de autenticação, com um exemplo realista de cada arquivo._ ## Paginação, sincronização incremental, endpoints dependentes e GraphQL A maioria das APIs não entrega todos os resultados em uma única resposta, e recarregar tabelas inteiras todos os dias fica lento. Para evitar isso, podemos usar a notação mostrada abaixo no arquivo do endpoint. ### Quatro tipos de paginação O bloco `pagination` dentro de `response` aceita um dos [quatro tipos](https://github.com/erathos-data/custom-api-connector): Tipo Use quando a API... Configurações principais `offset` pula N registros por requisição, como `?offset=200` `offset_size` (padrão 100), `path` opcional até a contagem total de registros `page` recebe um número de página, como `?page=3` `initial_value` (padrão 1), `path` opcional até a contagem total de páginas `token` retorna um cursor ou token "next" para a próxima requisição `path` até o token, obrigatório `time` recebe uma data de início e de fim em cada requisição `window_size_in_days`, `sort` e `cursor_timestamp_format`, obrigatórios O placeholder `` é usado para passar o valor atual de offset/número da página/token para a próxima requisição. Ele é substituído por `` e `` quando se usa paginação por tempo. Em ambos os casos, se o caminho da contagem total não for informado nos tipos de paginação offset ou page, o conector continua pedindo mais páginas até receber uma página vazia. A paginação por token é a forma padrão de paginação em APIs GraphQL. A [documentação do GraphQL considera a paginação baseada em cursor a abordagem "mais poderosa"](https://graphql.org/learn/pagination/) entre os padrões gerais, porque a abordagem por offset está sujeita a mudanças se novos registros forem inseridos entre as requisições. ### Sincronização incremental com campos de cursor Agora, a propriedade `cursor: true` é usada para a sincronização incremental. Ela diz à Erathos para armazenar o maior valor visto para aquele campo e inserir esse valor nas requisições seguintes, onde quer que o nome do campo seja usado como placeholder. No `orders.yml` temos `updated_since: ""`, o que garante que só busquemos os pedidos que foram atualizados desde a última sincronização. O `cursor_timestamp_format` no `_default.yml` define como essa data deve ser formatada. Observe que o placeholder precisa corresponder exatamente ao nome do campo. Então, se tivéssemos um campo chamado `updatedAt`, usaríamos `` como placeholder, e não ``. Observe também que vários campos podem ser usados como cursor. Isso se chama cursor composto e pode ser útil, por exemplo, se `updated_at` puder vir vazio em registros novos e você quiser usar tanto `created_at` quanto `updated_at` como cursor. Para a sincronização incremental do lado da Erathos, [exigimos tanto uma chave primária quanto um cursor de data](https://docs.erathos.com/platform/connections/sync-types). Esse é outro motivo pelo qual definimos `primary_key` acima. ### Endpoints dependentes Alguns dados só vêm de uma chamada de detalhe: você lista os pedidos e depois busca os itens de cada pedido. Um endpoint filho declara um endpoint pai e um campo dele: `dependency:` ` endpoint: orders` ` field: id` ` as: order_id` `request:` ` method: GET` ` endpoint: "/orders//items"` `response:` ` path: [data]` ` primary_key: [id]` `fields:` ` - name: id` ` type: string` ` - name: sku` ` type: string` ` - name: quantity` ` type: integer` Para cada registro retornado pelo endpoint `orders`, a Erathos chama `order_items`, substituindo `` pelo `id` do pedido correspondente. Um endpoint só pode depender de [um pai por meio de um campo](https://github.com/erathos-data/custom-api-connector), e endpoints filhos custam uma requisição por registro pai (isso pode ser mantido baixo após a primeira carga usando um cursor no pai). Por exemplo, com 3 pedidos, o endpoint filho faz 3 chamadas: ### GraphQL Um endpoint GraphQL usa `query` em vez de `params`. Você cola a query como está, sem precisar escapar as chaves. Esta versão reduzida do exemplo do template, baseada na API de issues do Linear, pagina com um token e filtra por um cursor: request: ` method: POST` ` endpoint: "/graphql"` ` query: >` ` {` ` issues(first: 250 filter: {updatedAt: {gte: ""}}) {` ` pageInfo { hasNextPage endCursor }` ` nodes { id title updatedAt state { name } }` ` }` ` }` `response:` ` path: [data, issues, nodes]` ` primary_key: [id]` ` pagination:` ` type: token` ` path: [data, issues, pageInfo, endCursor]` `fields:` ` - name: id` ` type: string` ` - name: title` ` type: string` ` nullable: true` ` - name: updatedAt` ` type: timestamp` ` cursor: true` ` cursor_timestamp_format: "%Y-%m-%dT%H:%M:%S.000Z"` ` - name: state.name` ` type: string` ` nullable: true` O caminho da resposta entra no envelope do GraphQL, e o caminho de paginação aponta para `endCursor` (que é o campo que o [modelo de connections do GraphQL](https://graphql.org/learn/pagination/) usa para indicar a próxima página). ## Do repositório ao conector Antes de fazer push, o validador do template verifica a pasta. Ele precisa do PyYAML e é executado a partir da raiz do repositório: pip install pyyaml python validate\_connector.py . Ele aponta chaves obrigatórias ausentes, chaves desconhecidas, tipos de campo inválidos, placeholders que não correspondem a nada e YAML que não pode ser interpretado. Com `url_base` removido do `_default.yml`, ele para com exit code 1: Validating connector YAML in: ./acme\_broken \_default.yml \[ERROR\] request.url\_base: missing required field Summary: 1 error(s), 0 warning(s) across 1 file(s). Observe que o validador só verifica se as estruturas batem. Um `response.path` que aponta para uma chave que a API nunca retorna ainda vai passar pelo validador. Um conector assim acabaria [sincronizando zero linhas](https://github.com/erathos-data/custom-api-connector). Por isso, antes de confiar em um novo endpoint, teste-o com uma resposta real. Para conectar seu repositório, siga os passos abaixo, conforme descrito na [documentação da Erathos](https://docs.erathos.com/connectors/custom-connectors): 1. Garanta que você tem acesso de admin na conta ou organização do GitHub dona do repositório. 2. Na Erathos, vá em **Connections → New Connection → Select datasource**, ou **Settings → Workspace → Repositories**, e clique em **Connect a custom connector via GitHub**. 3. No GitHub, a Erathos vai pedir que você instale o Erathos GitHub App. Escolha a conta ou organização onde quer instalar o app e selecione os repositórios que a Erathos poderá ler. 4. Depois de instalar o app no GitHub, o diálogo **Watch repository** abre na Erathos. Nele, informe o repositório no formato `owner/repo` (por exemplo, `your-org/your-connector`) e clique em **Watch repository**. 5. A Erathos então inicia o primeiro build. Ele pode levar alguns minutos, e a página Repositories é atualizada até o build terminar. 6. Quando o build é concluído com sucesso, o conector aparece no catálogo de fontes de dados com um selo **Custom**. [Owners da organização podem instalar apps na organização](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party), e você pode optar por deixar o app acessível apenas em **Only select repositories** em vez de todos os repositórios da conta ou organização. Se você for membro de uma organização e não tiver permissão para instalar apps nela, a solicitação será encaminhada a um owner da organização. Cada push no repositório monitorado dispara um rebuild da imagem do conector. Ou seja, todo push no repositório monitorado é um deploy. Isso significa que um erro de digitação mergeado numa sexta à tarde vai para produção no próximo build; por isso, usar o validador e passar por revisão de pull request pode valer o minuto extra. O fluxo completo, dos arquivos YAML até as linhas no seu warehouse, é: Em Settings → Workspace → Repositories, você vê a lista dos repositórios que monitora, além da branch. É também ali que você pode removê-los. Porém, ao clicar em "Remove", o conector deixa de ser reconstruído e sincronizado imediatamente, e não há como desfazer isso na página. ## Por que manter conectores como código O conector é um conjunto de arquivos no seu repositório, então ele é tratado como qualquer outro código do seu projeto. - **Revisão.** Todas as mudanças em endpoints passam por pull request. Outras pessoas do time conseguem ver que alguém mudou o `orders.yml` de paginação por página para paginação por token antes que essa mudança vá para produção. - **Histórico.** O Git registra as mudanças nos campos, além de quem as fez e quando. Se uma coluna começar a vir vazia, rode `git log orders.yml` para ver o que mudou. - **Rollback.** Como todo push no repositório dispara um rebuild do conector, reverter uma mudança ruim é tão simples quanto rodar `git revert` na mudança e depois rodar `git push` para fazer o deploy da versão anterior do conector. Como o conector deixa de ser um script que alguém escreveu, qualquer pessoa do time consegue entendê-lo depois de alguns minutos lendo os arquivos YAML. ## O que você ganha depois do deploy Se o build for bem-sucedido, você pode criar uma conexão a partir do conector com o selo **Custom**, informando as credenciais que você definiu, selecionando um schema de destino e habilitando os endpoints que quiser na seção **Manage Jobs**. A partir daí, ele vai [funcionar como qualquer conector nativo](https://www.erathos.com/en/blog/custom-api-connector-ai-agent?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code): - **Um job por endpoint**, com sua própria frequência, agendamento e tipo de sincronização. Endpoints filhos aparecem com o gatilho **Parent Job** e [só rodam depois da execução bem-sucedida do job pai](https://docs.erathos.com/platform/connections/jobs). - **Full refresh ou sincronizações incrementais**: o full refresh carrega o endpoint inteiro a cada execução. Os [tipos incrementais (parciais)](https://docs.erathos.com/platform/connections/sync-types) carregam apenas os registros após o cursor e exigem que a `primary_key` e o campo de cursor estejam definidos no arquivo YAML. - **Histórico de execuções**: cada execução é registrada como sucesso ou falha, junto com todos os outros conectores. Logs, timestamps, métricas e erros ficam disponíveis na [página de execuções](https://docs.erathos.com/platform/runs-history) de cada execução. - **Rastreabilidade por linha**: colunas de controle, como `_erathos_execution_id` e `_erathos_synced_at`, são adicionadas a todas as tabelas carregadas. Isso permite rastrear qualquer linha até a execução que a carregou e o momento em que foi carregada. A [página de controle da Erathos](https://www.erathos.com/en/control?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code) traz mais detalhes sobre as opções disponíveis no nível do job, como disparar jobs via API, executá-los a partir do Airflow ou do Dagster, estratégias de retentativa etc. ## Criando os arquivos com um agente de IA Também criamos uma skill de agente de IA para este repositório template. A skill lê a documentação da API e depois faz as perguntas que ficaram em aberto. Ela escreve os arquivos YAML para você e roda o validador. Ela também adiciona um comentário `# UNVERIFIED` em cada linha que não conseguiu confirmar pela documentação. Assim, você pode focar em testar essas linhas primeiro. Escrevemos um [post no blog sobre essa skill de agente de IA](https://www.erathos.com/en/blog/custom-api-connector-ai-agent?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code), em que percorremos a skill passo a passo e criamos um conector completo para uma API real. ## Limites da notação YAML A notação para custom connectors cobre [autenticação por header estático ou token e OAuth2, os quatro tipos de paginação e respostas que podem ser alcançadas com uma lista `path` simples](https://github.com/erathos-data/custom-api-connector). Ela não cobre, porém, todas as estruturas de API possíveis. Por exemplo, algumas APIs usam métodos de autenticação diferentes de headers estáticos, tokens e OAuth2, como assinar cada requisição. Da mesma forma, algumas APIs usam métodos de paginação diferentes de offset, page, token e time. As APIs também podem retornar respostas com estruturas complexas, que não podem ser alcançadas com uma simples lista de chaves ou que precisam ser combinadas a partir de vários pontos de uma mesma resposta. Por fim, as dependências entre endpoints podem ser mais complexas do que um único endpoint filho dependendo de um único campo de um único endpoint pai. Em todos esses casos, o template de custom connector recomenda parar e perguntar, em vez de tentar forçar o caso no campo mais próximo do template. Custom connectors também não são indicados para bancos de dados, arquivos ou outras fontes que já têm conectores nativos da Erathos. Esses conectores nativos são mantidos pela Erathos. Por fim, um detalhe de configuração fácil de passar despercebido: os arquivos de exemplo do template são endpoints válidos, então qualquer arquivo `example_*.yml` que não for apagado antes do próximo push será criado como um endpoint ativo. ## Custom Connector, conector nativo ou script caseiro? Aqui vai um guia rápido para ajudar você a escolher entre essas opções: - Use um conector nativo se a sua fonte já tiver um. Você pode navegar pelo [catálogo de conectores da Erathos](https://www.erathos.com/en/connectors?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code) e solicitar um conector por lá, caso a sua fonte ainda não tenha um e você não queira manter um repositório por conta própria. - Use um Custom Connector se a sua fonte for uma API HTTP com respostas em JSON, não tiver um conector nativo e puder ser descrita com a notação (autenticação, paginação, estrutura da resposta). Exemplos são APIs internas, ferramentas SaaS de nicho e sistemas regionais. - Use um script se a sua API usar uma autenticação, paginação ou estrutura de resposta que a notação não cobre, se a sua fonte não for uma API HTTP ou se você precisar fazer uma extração pontual que nunca vai se repetir. Observe que o Custom Connector está disponível no [plano Pro](https://www.erathos.com/en/pricing?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code). ## Perguntas frequentes ### Preciso saber Python para criar um Custom Connector? Não. Você só escreve arquivos YAML descrevendo a API, e há uma linha no template que diz explicitamente que você não vai escrever nenhum código Python. O único Python envolvido é rodar o script do validador, que é um único comando. ### Onde ficam armazenadas as credenciais da API? As credenciais nunca vão para o seu repositório. O arquivo YAML contém apenas placeholders como ``. Ao criar uma conexão na Erathos, você informa os valores reais desses placeholders, e os valores `secret` ficam mascarados na interface. ### O que acontece se a API mudar? Depois de fazer as alterações necessárias no arquivo YAML do endpoint afetado pela atualização da API, abrimos um pull request e fazemos o merge das mudanças no conector. O push no conector dispara um rebuild, e a próxima sincronização aparece no histórico de execuções como falha caso não tenha dado certo. ### Posso usar um Custom Connector com uma API GraphQL? Sim. Um endpoint GraphQL coloca a query em `request.query`. O GraphQL usa POST, e a paginação geralmente é feita com o tipo `token` apontando para o campo `endCursor`. ### Como faço rollback de uma mudança ruim? Reverta o commit e faça push. Todo push no repositório monitorado dispara um rebuild do conector, e o revert restaura a versão anterior no próximo build. ## Teste com a sua própria API Teste a API por trás do script mais chato que você tem. Copie o template, descreva um endpoint, rode o validador e monitore o repositório. [Teste a Erathos grátis por 14 dias](https://app.erathos.com/signup?utm_source=blog&utm_medium=organic&utm_content=bydefault&utm_campaign=custom-api-connector-as-code). Durante o período de teste, você tem acesso à versão Pro da Erathos. Não é necessário cartão de crédito.