Resposta direta
Implementar uma API começa por escrito, não pelo código. Antes da primeira chamada, ficam definidos: quais campos trafegam e com que significado, o que acontece quando uma chamada falha, como uma mesma mensagem é reprocessada sem duplicar registro, quem é acionado quando o outro lado não responde e como volume e latência são acompanhados. Sem essas definições, a integração funciona no teste e vira chamado no plantão. A API é o meio. A decisão sobre dado, erro e responsabilidade é o que sustenta a operação.
- Objetivo
- Orientar implementação
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata a API como combinação operacional de dado, falha e responsável, em vez de escolha de tecnologia
O contrato de dados antes do código
Antes de escolher formato ou transporte, o que precisa estar escrito é o significado de cada campo: nome, tipo, se é obrigatório, de onde vem e o que representa quando chega vazio. Campo vazio e campo ausente não são a mesma coisa na operação, e essa diferença precisa estar combinada, não descoberta em produção.
Cada campo tem um dono. Se o cadastro nasce em um sistema, é ele que responde pelo conteúdo, mesmo que o dado trafegue para outro. Sem essa definição, os dois lados corrigem o mesmo problema em lugares diferentes e o erro volta na troca seguinte.
O que acontece quando a chamada falha
Toda chamada pode falhar. A pergunta útil não é se vai falhar, mas o que ocorre quando falha: quem tenta de novo, em que intervalo, por quanto tempo e o que o sistema faz depois de esgotar as tentativas. Isso precisa estar decidido antes de ligar, porque decidir durante o incidente custa mais e costuma ficar pela metade.
Reprocessar sem critério duplica registro. A chave que identifica uma mensagem e permite reconhecer a repetição faz parte da implementação. O mesmo vale para limite de requisições e para o volume esperado: são condições de operação, não surpresas do primeiro dia.
O que a API não resolve
Uma API bem implementada não corrige dado errado na origem nem resolve divergência de definição entre áreas. Se duas equipes entendem 'cliente ativo' de formas diferentes, a integração transporta essa diferença com eficiência. O problema continua sendo de processo e de responsabilidade, não de interface.
Há situações em que implementar API não é o caminho. Troca esporádica, com poucos registros e sem necessidade de tempo real, pode ser atendida por outro arranjo, com menos superfície de manutenção. A decisão depende de volume, frequência e custo de erro, que precisam ser medidos antes, não estimados por impressão.
Recurso prático
O que precisa ficar registrado antes de ligar a integração
| Decisão | O que fica registrado |
|---|---|
| Campos e significados | Nome, tipo, obrigatoriedade, origem e o que representa um campo vazio ou ausente |
| Comportamento em falha | Quem tenta de novo, em que intervalo, até quando e o que acontece depois do limite |
| Reprocessamento | Como reconhecer uma mensagem repetida e evitar gravar o mesmo registro duas vezes |
| Responsável | Quem é acionado quando a chamada falha fora do horário e em quais casos |
O erro mais comum é detalhar os campos com cuidado e deixar o comportamento em falha para depois. É essa parte que decide se a integração aguenta a operação.
Sobre o que está escrito aqui
Conceitos relacionados: contrato de dados · idempotência · fila de reprocessamento · versionamento de API · responsável pela integração. Exemplos são ilustrativos. Não há cliente, resultado, preço, prazo ou certificação nesta página. Quando o formato indicado é Projeto de implementação, ele descreve uma possibilidade de trabalho — a conversa inicial avalia contexto e aderência.
Para continuar
- Integrações, sistemas e qualidade de dados — Página central do tema
- Cadastros duplicados: como descobrir e consol… — cadastros duplicados
- Exportações manuais: quando ainda fazem sentido — exportações manuais
Páginas relacionadas
O mesmo problema em outro objetivo
- API sem erro aparente: como testar o que ela devolve — Diagnosticar
- APIs sem dono: como definir responsabilidade e contrato — Organizar um processo
- Duas APIs para o mesmo dado: o que decide a escolha — Comparar alternativas
- APIs sem medição: o que acompanhar depois de conectar — Explicar medição
Outras leituras em Integrações, sistemas e qualidade de dados
- Integração sem documentação: o que comparar antes de mexer — Compara quatro caminhos para uma integração sem documentação e indica o que observar em cada um: dependências, teste, responsável e custo de erro.
- Integração sem monitoramento: o que verificar primeiro — Como levantar o estado real de uma integração sem monitoramento: onde olhar, o que registrar e quais sinais indicam risco de falha.
- Falha na sincronização: como comparar o monitoramento — Compara as formas de acompanhar falha na sincronização, o que cada uma percebe, em quanto tempo e a que custo de operação.
- Data e hora sem fuso: o que exigir no contrato — O que declarar, testar e escrever no contrato ao receber dados com data e hora sem fuso, e onde essa exigência não resolve.
- Log de integração sem nível de erro: o que registrar — A página trata da classificação de eventos no log de integração: o que distinguir, onde gravar a decisão e como revisar sem depender de memória.