Resposta direta
Organizar APIs é registrar, para cada uma, a operação que depende dela, a área que responde pela mudança e o contrato de dados que ela entrega. O registro é um documento de operação, não um inventário técnico. Sem responsável nomeado, a mudança de uma API acontece sem aviso a quem consome. Sem contrato descrito, cada consumidor interpreta campos vazios de um jeito. A ordem prática é levantar o que já existe em produção, atribuir responsável e só então padronizar formato e versão. Padronizar antes do levantamento costuma produzir documento que ninguém mantém.
- Objetivo
- Organizar um processo
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata o ciclo de vida da API em produção, com responsável, contrato e descontinuação, em vez de tratar integração como decisão de compra ou como problema de sincronização de dados.
O catálogo começa pela operação
Antes de listar endpoints, o levantamento pergunta qual decisão cada integração alimenta. Uma API que envia posição de estoque para o faturamento existe por causa de uma regra de negócio. Descrever essa regra é o que dá sentido ao registro e permite avaliar o impacto quando algo mudar.
O levantamento costuma revelar integrações que ninguém sabe explicar. Duas áreas consomem o mesmo dado por caminhos diferentes, ou uma planilha intermediária esconde a dependência real. Registrar essas situações é parte do trabalho, não desvio dele.
Responsável, contrato e versão
Cada API precisa de uma área que responda por ela, com nome e não apenas com o time de tecnologia. Essa área decide o que pode mudar, avisa os consumidores e acompanha quem ainda usa versões antigas.
O contrato de dados descreve campos, formato, obrigatoriedade e o que acontece quando um campo chega vazio. Sem isso, cada consumidor cria a própria regra de exceção, e a divergência volta pela porta dos fundos.
O que o catálogo não resolve
O registro não corrige dado errado na origem nem substitui validação na entrada. Também não impede que uma área mude um campo sem avisar; ele torna a falha visível e localizável, o que já é diferente de evitá-la.
Em operações com poucas integrações e um único responsável, o catálogo formal não compensa o esforço de manter. O mesmo vale quando a decisão sobre a API não pertence a nenhuma área da empresa: aí o problema é de governança, e nenhum registro resolve isso sozinho.
Recurso prático
Catálogo mínimo de uma API em uso
| Item do registro | O que precisa estar descrito |
|---|---|
| Operação que depende | qual decisão a integração alimenta e o que para quando ela falha |
| Área responsável | quem decide a mudança, quem avisa os consumidores e quem responde pelo erro |
| Contrato de dados | campos, formato, obrigatoriedade e o tratamento de campo vazio |
| Versão em uso | quem consome, desde quando e o que está combinado para descontinuar |
O erro mais comum é registrar a API pelo nome técnico do endpoint. Quem consulta o catálogo não procura por endpoint; procura pela operação que deixou de funcionar.
Sobre o que está escrito aqui
Conceitos relacionados: catálogo de APIs · contrato de dados · área responsável · versão em uso · descontinuação de 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
- Números que não batem: por que a divergência… — planilhas divergentes
- Sincronização entre sistemas: o que decidir a… — sistemas desconectados
Páginas relacionadas
O mesmo problema em outro objetivo
- API sem erro aparente: como testar o que ela devolve — Diagnosticar
- 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
- Base de teste diferente da produção: o que padronizar — Define o que a base de teste precisa reproduzir da produção, quem responde por mantê-la e quando ela deixa de servir para validar.
- Exportação como integração permanente: o que formalizar — O que uma exportação precisa ter para virar integração permanente: contrato de dados, responsável, conferência de fechamento e critério de falha.
- 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.
- 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.
- Arquitetura de integração: o que comparar antes de decidir — A página compara arquiteturas de integração por onde mora a regra, quem responde pelo dado, reversibilidade e custo de mudança ao longo do tempo.