Resposta direta
A comparação começa pelo contrato, não pela documentação. O que importa é o que cada API entrega sobre campos, formatos, frequência de atualização e comportamento em erro. Depois entra o custo de trocar: quanto do mapeamento fica do lado de quem consome e quanto precisa ser refeito se o fornecedor mudar a versão. Duas APIs podem entregar o mesmo dado e falhar de formas diferentes. A escolha raramente é técnica; é sobre quem assume a responsabilidade quando o dado chega errado ou atrasado.
- Objetivo
- Comparar alternativas
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Coloca candidatas lado a lado pelo contrato, pelo comportamento em falha e pelo custo de troca, em vez de comparar funcionalidades anunciadas.
O que só aparece em uso
A documentação descreve o caminho normal. Raramente descreve o que acontece quando um campo vem vazio, quando o registro não existe ou quando a mesma chamada é repetida. São esses casos que definem o esforço de operação.
Duas APIs com o mesmo dado tratam ausência de formas diferentes. Uma devolve erro, outra devolve campo nulo, outra omite o campo. Cada escolha gera código de tratamento distinto e, depois, incidentes distintos.
Custo de troca e responsabilidade
Trocar de API nunca é só trocar o endereço. Parte da validação, do mapeamento e das regras de exceção vive no lado de quem consome. Se o fornecedor muda formato sem aviso, esse trabalho volta inteiro.
Vale registrar quem responde pelo dado incorreto. Sem essa definição, a correção vira discussão entre áreas e o erro continua visível para quem está na ponta.
Onde a comparação não decide
Comparar APIs não resolve dado que nasce errado na origem nem cadastro divergente entre áreas. São questões de processo e de responsabilidade, anteriores à integração.
Também não existe critério que substitua teste com dado real. A matriz aponta o que verificar; não confirma comportamento em volume, sob carga ou em falha parcial. Isso só aparece operando.
Recurso prático
Comparação lado a lado de duas APIs candidatas
| O que se avalia | Pergunta que resolve |
|---|---|
| Cobertura de campos | Quais campos vêm na resposta e quais dependem de uma segunda chamada ou de outra fonte |
| Comportamento em falha | O que a API devolve quando o dado falta, atrasa ou vem incompleto |
| Política de versão | Com quanto tempo de aviso mudanças quebram o que já está em produção |
| Custo de troca | Quanto do mapeamento e da validação vive do lado de quem consome e volta a ser trabalho ao migrar |
O erro mais comum é decidir pela documentação e pelo preço por chamada. A documentação descreve a intenção; o que decide é o comportamento observado em campo ausente, registro inexistente e chamada repetida.
Sobre o que está escrito aqui
Conceitos relacionados: contrato de API · versionamento · tratamento de erro · mapeamento de campos · custo de troca. 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
- Sincronização entre sistemas: o que decidir a… — sistemas desconectados
- Falhas silenciosas em integrações: como perce… — falhas silenciosas
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
- APIs sem medição: o que acompanhar depois de conectar — Explicar medição
- Integração por API: o que definir antes de ir para produção — Orientar implementação
Outras leituras em Integrações, sistemas e qualidade de dados
- Relatório sem assinatura: rastrear a origem do número — Mostra quem montou o relatório, qual regra foi aplicada e qual base foi usada, para separar divergência de dado de divergência de critério.
- Erro de sincronização visto pelo cliente: por onde começar — Registro, contenção, correção e fechamento de um erro de sincronização apontado pelo cliente, com responsável e critério de encerramento.
- Alertas que ninguém lê: o que vigiar e quem responde — Sinais, responsáveis e cadência de revisão na observabilidade de sistemas, e o que esse arranjo não cobre.
- Sistema antigo que ninguém desliga: como planejar o fim — Decisão sobre o destino de sistemas ainda em uso, com responsável por etapa e registro do que depende deles antes do desligamento.
- Sistema antigo só de histórico: o que sai da operação — O que ainda precisa rodar no sistema antigo, o que passa a ser consulta histórica e quem responde pela leitura de cada dado.