Disponibilidade e compatibilidade resolvem problemas diferentes. Um endpoint pode retornar HTTP 200 com uma estrutura que o consumidor deixou de entender. A governança conecta decisões de projeto, responsáveis e evidências de uso para proteger o processo de negócio por trás da chamada.
1) O risco das mudanças sem governança
Imagine uma API de pedidos com uma referência externa opcional. Tornar esse campo obrigatório rejeita requisições que eram válidas ontem. Para o provedor, a edição parece pequena; para o consumidor, houve quebra de contrato.
- Tornar um campo de entrada obrigatório ou mudar seu tipo.
- Trocar uma lista por um objeto, remover um campo ou alterar seu significado.
- Exigir novos scopes, outro mecanismo de autenticação ou certificados diferentes.
- Reduzir quotas ou limites de consumo sem acordar a transição.
Até a adição de um campo pode afetar clientes com validação estrita. Avalie compatibilidade com testes dos consumidores. As políticas de proteção de endpoints com API Management também compõem o comportamento observado.
2) Defina o contrato mínimo antes de publicar
Documente recursos, métodos, schemas de entrada e saída, campos obrigatórios, códigos de erro, paginação, datas, fusos horários e regras de idempotência. Use OpenAPI quando adequado, com exemplos e critérios de aceite. O schema sozinho não descreve todas as regras de negócio.
Acorde autenticação, autorização, limites, tempos de resposta esperados e suporte. Identifique owners técnico e funcional e um contato de migração para cada consumidor. Uma matriz de ownership esclarece quem aprova a mudança e quem responde por incompatibilidades.
3) Quando criar uma nova versão
Uma correção que preserva o contrato pode permanecer na versão atual após testes de regressão. Uma mudança incompatível exige nova versão do contrato ou uma transição explícita aceita por todos os afetados. Não altere silenciosamente a v1 para avisar depois.
No SAP API Management, uma revisão do proxy não equivale a uma nova versão do contrato para consumidores. Planeje um mecanismo estável de versionamento e um período de convivência. Um novo número não protege a v1 se ambas dependem de um backend que deixou de suportá-la.
4) Descontinuar exige uma migração acompanhada
- Disponibilize o substituto com diferenças documentadas, data prevista de retirada e suporte à migração.
- Notifique consumidores e registre planos e responsáveis.
- Teste as duas versões e observe o tráfego real durante a convivência.
- Investigue chamadas residuais, inclusive processos mensais ou esporádicos.
- Aprove a retirada com evidências, comunicação final e procedimento de recuperação.
Marcar uma API como deprecated comunica uma intenção, sem comprovar que a migração terminou. Revise certificados, segredos e endpoints compartilhados antes de remover dependências.
5) Mantenha um catálogo pequeno e útil
Registre finalidade de negócio, versão, estado do ciclo de vida, URLs por ambiente, contrato e repositório, owners, consumidores, dependências, políticas de acesso e data de retirada quando aplicável. Inclua o último teste de compatibilidade e links para monitoramento e runbooks. Guarde referências aos segredos, nunca seus valores.
6) Monitore por consumidor e resultado
Associe chamadas a uma identidade técnica autenticada, como uma aplicação cliente. Um header arbitrário enviado pelo cliente não autoriza acesso. Acompanhe erros, latência e rejeições por quota por consumidor e versão, comparando com uma linha de base.
Um Correlation ID de ponta a ponta ajuda na investigação, mas não substitui a identidade do cliente. Minimize dados pessoais nos logs e conecte alertas ao plano de continuidade do Integration Suite.
Checklist de liberação
- Contrato revisado e mudança classificada quanto à compatibilidade.
- Consumidores, owners e comunicação definidos.
- Testes de schema, autorização, erros, limites e regressão aprovados.
- Backend compatível durante toda a convivência.
- Monitoramento por versão e consumidor, janela e responsável definidos.
- Rollback testado considerando dados já processados.
A liberação termina quando o consumidor continua alcançando o resultado esperado. Consulte API Versioning da SAP e API Revisions para os mecanismos da plataforma.