Resposta direta
Diagnosticar uma API é testar o comportamento dela em condições ruins, não ler a documentação. O primeiro passo é provocar erro: campo faltando, valor fora do formato, identificador inexistente. A resposta mostra se a falha volta como erro visível ou como retorno vazio, que passa despercebido no relatório. O segundo ponto é o significado do dado: campo vazio pode ser ausência ou falha de leitura, data pode vir em fuso local ou UTC. O teste que costuma faltar é o da repetição: o que acontece quando a mesma chamada é feita duas vezes. Sem ele, a integração funciona no cenário feliz e falha em produção.
- Objetivo
- Diagnosticar
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata a API como comportamento observável sob falha, e não como contrato descrito em documentação.
Provar o erro antes do caminho feliz
Uma API se conhece pelo que ela faz com dado ruim. Campo faltando, valor fora do formato e identificador inexistente mostram se a falha volta como erro ou como resposta vazia. A diferença importa: erro é visível para quem opera, resposta vazia passa como ausência de dado e some no relatório.
O tempo de espera segue a mesma lógica. Toda chamada tem um limite, e o que fica gravado quando esse limite estoura define se a operação consegue reprocessar ou se perde o registro. Esse comportamento raramente está descrito na documentação e só aparece quando é provocado.
O que a resposta não diz sozinha
Retorno sem erro não significa dado correto. Campo vazio pode ser ausência real, falha de leitura ou valor não preenchido na origem, e cada caso pede tratamento diferente. Quem consome a API precisa saber qual é qual antes de decidir o que fazer com o registro.
Formato e significado também exigem conferência. Data em fuso local ou UTC, valor em centavos ou em reais, campo que muda de nome entre versões: são pontos que passam na validação técnica e quebram a conta depois. A conferência é comparar o mesmo registro na origem e no destino.
O que o teste não resolve
Testar a API não corrige a qualidade do dado na origem. Se o cadastro entra errado no sistema que expõe a API, o diagnóstico mostra o erro chegando, não o erro resolvido. A responsabilidade pela correção fica com quem mantém o sistema de origem.
O teste também é uma foto. Ele não representa o comportamento sob volume real, nem cobre mudanças feitas pelo fornecedor sem aviso. Repetir a bateria de testes em intervalos definidos é o que sustenta a confiança. Sem repetição, o resultado vale para o dia em que foi feito.
Recurso prático
O que testar e o que a resposta revela
| Teste aplicado à chamada | O que a resposta revela |
|---|---|
| Campo obrigatório ausente | Se a API rejeita a chamada ou grava valor padrão sem avisar |
| Mesma chamada enviada duas vezes | Se a operação duplica o registro ou pode ser repetida sem efeito novo |
| Lista longa dividida em páginas | Se itens se repetem ou desaparecem nas bordas entre páginas |
| Valor no limite do formato aceito | Se o campo é validado de fato ou truncado em silêncio |
| Chamada sem resposta dentro do tempo esperado | Se existe tempo limite definido e o que fica gravado quando ele estoura |
O ponto mais ignorado é ler o código de sucesso como prova de dado correto. O retorno sem erro confirma que a chamada chegou, não que o conteúdo está certo.
Sobre o que está escrito aqui
Conceitos relacionados: código de erro e resposta vazia · idempotência da chamada · paginação de listas · fuso e formato de data · tempo limite da chamada. 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
- APIs e integração: o que perguntar antes de c… — sistema sem integração
- Dados desatualizados: o que precisa estar em dia — dados desatualizados
Páginas relacionadas
O mesmo problema em outro objetivo
- 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
- 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
- Sistemas desconectados: como ordenar o fluxo de trabalho — Roteiro prático para estabelecer custódia de dados, regras de passagem e prioridades operacionais em empresas com ferramentas desconectadas.
- Cliente duplicado entre áreas: como medir a sobreposição — Define o que conta como cliente duplicado, qual base serve de referência e como acompanhar a sobreposição entre áreas ao longo do tempo
- Campo numérico aceita texto: o que fica gravado — Mostra onde a aceitação de texto em campo numérico começa, o que conferir entre tela, base e relatório e quais limites essa checagem não cobre.
- Fila sem limite de tempo: como pôr prazo e dono em cada etapa — O que definir para uma fila de processamento ter prazo, responsável e critério de encerramento, e o que essa estrutura não resolve.
- Planilha de apoio sem versão: como definir a cópia válida — Dono, nome, data de corte e conferência de uma planilha de apoio, e o ponto em que ela deixa de ser exceção e vira requisito de sistema.