Checklist de Versionamento
Guia prático para avaliar mudanças em APIs e eventos — como distinguir mudanças breaking de non-breaking e o que verificar antes de fazer deploy.
Para que serve um checklist?
Toda vez que você modifica uma API ou um schema de evento, precisa avaliar o impacto da mudança. Este checklist ajuda a classificar mudanças, identificar riscos e tomar as ações corretas antes que a mudança chegue à produção.
Classificação de mudanças
Mudanças non-breaking (seguras)
Essas mudanças são compatíveis com versões anteriores e geralmente podem ser implantadas sem coordenação:
- ✅ Adicionar um campo novo opcional a uma resposta de API
- ✅ Adicionar um novo endpoint
- ✅ Adicionar um parâmetro de query opcional
- ✅ Adicionar um campo novo opcional a um evento (com default)
- ✅ Adicionar um novo tipo de evento
- ✅ Ampliar a documentação ou descrições
- ✅ Melhorar mensagens de erro sem mudar códigos de status
- ✅ Adicionar novos códigos de status para casos não cobertos antes
Mudanças breaking (exigem coordenação)
Essas mudanças quebram consumidores existentes e exigem uma estratégia de migração:
- ❌ Remover um campo de uma resposta de API
- ❌ Renomear um campo existente
- ❌ Mudar o tipo de um campo (string → number, object → array)
- ❌ Tornar obrigatório um campo que era opcional
- ❌ Remover um endpoint
- ❌ Mudar a URL de um endpoint
- ❌ Remover um campo de um evento
- ❌ Mudar a semântica de um campo existente
- ❌ Reduzir os valores aceitos em um enum
- ❌ Mudar códigos de status HTTP para casos existentes
Mudanças cinzentas (avaliar caso a caso)
Essas mudanças podem ou não ser breaking dependendo do contexto:
- ⚠️ Adicionar um novo valor a um enum — breaking se os consumidores fizerem switch exaustivo
- ⚠️ Mudar um campo opcional para obrigatório em um request — breaking para consumidores que não o enviavam
- ⚠️ Adicionar validações mais rígidas — breaking para consumidores que enviavam dados antes aceitos
- ⚠️ Mudar a ordem de campos em uma resposta — breaking se algum consumidor depender da ordem
Checklist para mudanças em APIs
Antes de fazer deploy de uma mudança em uma API, verifique cada ponto:
1. Análise de impacto
- Você identificou todos os consumidores deste endpoint?
- Você revisou os contract tests (se existirem) para este endpoint?
- A mudança é backward compatible?
- Se for breaking, você definiu uma estratégia de migração?
2. Versionamento
- A mudança exige uma nova versão da API?
- Se for non-breaking, ela pode ser incluída na versão atual?
- Você atualizou a documentação da API (OpenAPI/Swagger)?
- Você adicionou a mudança ao changelog?
3. Comunicação
- Você notificou as equipes consumidoras?
- Se for breaking, você definiu um período de coexistência?
- Você adicionou headers de depreciação, se aplicável?
- A data de sunset está comunicada e documentada?
4. Testes
- Os contract tests passam com a mudança?
- Você testou que os consumidores existentes continuam funcionando?
- Você adicionou testes para o novo comportamento?
- Você executou can-i-deploy (ou equivalente)?
5. Deploy
- A ordem de deploy está correta? (geralmente o produtor primeiro para mudanças non-breaking)
- Você tem um plano de rollback caso algo dê errado?
- Você configurou monitoramento para detectar erros pós-deploy?
Checklist para mudanças em eventos
1. Análise de compatibilidade
- A mudança é backward compatible? (consumidores novos leem eventos antigos)
- A mudança é forward compatible? (consumidores antigos leem eventos novos)
- Os campos novos têm valores padrão?
- Os consumidores existentes ignoram campos desconhecidos?
2. Schema Registry
- Você registrou o schema novo no schema registry?
- A validação de compatibilidade passou?
- Você atualizou a versão do schema?
- Você documentou as mudanças no schema?
3. Upcasting (se aplicável)
- Você precisa de um upcaster para eventos históricos?
- O upcaster é determinístico e sem efeitos colaterais?
- Você testou a cadeia completa de upcasters?
- Os consumidores que reprocessam eventos históricos funcionam corretamente?
4. Consumidores
- Todos os consumidores conseguem lidar com o novo formato?
- Os consumidores têm tratamento de erros para schemas inesperados?
- A ordem de deploy está correta? (geralmente os consumidores primeiro para mudanças backward compatible)
Processo recomendado para mudanças
Para mudanças non-breaking
- Implementar a mudança no produtor
- Atualizar documentação e changelog
- Fazer deploy do produtor
- Notificar os consumidores sobre as novas capacidades
- Os consumidores adotam a mudança no próprio ritmo
Para mudanças breaking
- Comunicar a mudança com antecedência
- Criar a nova versão (API) ou schema (eventos)
- Implementar período de coexistência
- Fazer deploy da nova versão junto com a anterior
- Coordenar a migração dos consumidores
- Monitorar a adoção da nova versão
- Depreciar a versão anterior com data de sunset
- Retirar a versão anterior quando não tiver mais tráfego
Sinais de alerta
Preste atenção a estes sinais que indicam problemas no seu processo de versionamento:
- 🚩 Você não sabe quantos consumidores sua API tem
- 🚩 Você não tem contract tests
- 🚩 As mudanças breaking são descobertas em produção
- 🚩 Não há changelog nem documentação de versões
- 🚩 As equipes têm medo de mudar APIs por não saber o que vai quebrar
- 🚩 Há múltiplas versões ativas sem data de sunset
- 🚩 Os eventos não têm campo de versão no schema