Resposta direta
Medir API é medir o que a operação perde entre a saída de um sistema e a chegada no outro. Disponibilidade não basta: um serviço pode responder em tempo e devolver dado incompleto. A medição precisa de quatro registros, o que foi enviado, o que foi recebido, o que foi recusado e quem responde por cada recusa. Sem essa separação, o número agregado esconde a origem do problema. A comparação entre origem e destino é a parte que costuma faltar, porque exige contagem dos dois lados e não apenas do lado que chama o serviço.
- Objetivo
- Explicar medição
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata medição como conciliação entre origem e destino, e não como painel de disponibilidade.
O que entra na medição além de disponibilidade
Disponibilidade responde a uma pergunta estreita: o serviço respondeu. Não diz se o dado chegou completo, se foi aceito ou se virou duplicidade no destino. Uma operação pode responder em tempo e recusar parte das chamadas por regra de validação, sem que isso apareça no painel de infraestrutura.
A medição útil começa pela lista de operações com nome de negócio, não pelo nome do endpoint. Cada uma precisa registrar o que foi enviado, o que foi aceito, o que foi recusado e por qual motivo. Separar recusa de indisponibilidade é o que permite atribuir a falha a contrato, a dado ou a infraestrutura.
A comparação entre origem e destino
A divergência entre o que saiu de um sistema e o que chegou no outro é o dado que costuma faltar. Medir apenas o lado que chama o serviço produz visão parcial: erro de envio não contabilizado aparece como silêncio, não como falha.
A conferência pede contagem do mesmo período nos dois lados, por operação e por identificador. Quando a diferença aparece, o passo seguinte é classificar: item perdido, item duplicado, item aceito com dado alterado. Cada classe aponta para um responsável diferente.
O que a medição não resolve
Medir não corrige contrato mal definido nem sistema que muda regra sem avisar. Se a origem não registra o que enviou, nenhum painel reconstitui o que faltou.
A medição também não decide prioridade nem substitui responsável. Ela mostra onde a operação perde e desde quando. A escolha do que arrumar primeiro continua sendo de negócio, e um conjunto de métricas sem dono tende a virar acompanhamento decorativo.
Recurso prático
Checklist de medição por operação de API
- Para cada operação exposta, o que é enviado, o que é aceito e o que é recusado.
- Taxa de erro separada por tipo: dado inválido, indisponibilidade, tempo esgotado.
- Contagem na origem e no destino do mesmo período, por operação e por identificador.
- Fila de retentativa com idade do item mais antigo e motivo da última falha.
- Tempo de resposta medido na operação, não na média do serviço inteiro.
- Nome do responsável por cada tipo de falha e o canal onde ela é discutida.
- Histórico guardado além do painel do dia, para comparar comportamento ao longo do tempo.
O erro mais comum é medir só o lado que chama o serviço. Sem contagem na origem, falha de envio aparece como ausência de erro.
Sobre o que está escrito aqui
Conceitos relacionados: taxa de erro por operação · conciliação entre origem e destino · fila de retentativa · tempo de resposta por operação · responsável por tipo de falha. 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
- 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
- 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
- Dado sem histórico de origem: reconstruir o rastro mínimo — Reconstrução do rastro mínimo de um dado sem histórico de origem e definição do que passa a ser registrado em cada carga.
- Chave de ligação ausente: o que medir antes de corrigir — Medição de chave de ligação ausente entre cadastros: denominador, corte por origem, taxa por período e leitura das lacunas que impedem conciliação.
- Retrabalho de conciliação no fechamento: o que contratar — O que avaliar ao contratar apoio para o retrabalho de conciliação no fechamento, com escopo, responsabilidade sobre divergência, medição e limites.
- Tempo de resposta do sistema: quatro arranjos de processo — Compara arranjos para absorver a espera do sistema no processo: mudar a ordem das etapas, criar fila, sobrepor tarefas ou reduzir a dependência.
- Relatório sem assinatura: alternativas e limites de cada uma — Compara três caminhos para relatório sem autoria: bloquear a publicação, exigir registro na origem e aceitar com ressalva após reconciliação.