Versionamento de interfaces: como mudar sem quebrar
O que conta como mudança que quebra
Remover um campo ou rota, mudar um tipo, tornar obrigatório um campo opcional, mudar o significado de um valor existente e apertar limites. Adicionar um campo opcional não quebra — desde que os consumidores ignorem campos que não reconhecem, uma regra que vale documentar.
Como gerenciar uma transição
Rode a nova versão junto com a antiga, meça quem ainda usa a antiga, e desligue só depois que o uso chegar a zero ou depois de dar aviso suficiente.
Poucas versões com conteúdo significativo vencem uma versão por pequena mudança. Cada versão viva é código para manter e testar.
Deprecar gradualmente
Marque campos e rotas como programados para remoção na documentação e em um cabeçalho de resposta, com uma data. Envie um aviso aos consumidores ativos. E por último, antes de desligar — faça uma 'escuridão controlada': desligue por alguns minutos e veja quem grita.
Indo mais fundo
Mantenha métricas por versão e por consumidor, não só por rota. Sem isso, desligar uma versão antiga é uma aposta, e quem for afetado vai descobrir na própria produção — ou seja, numa ligação urgente que chega até você.