Compatibilidade é uma janela de transição
Em ambientes corporativos, servidor, aplicativo móvel, desktop e integrações raramente mudam no mesmo instante. A versão nova precisa conviver com a anterior por um período definido. O problema real, portanto, não é apenas versionar uma URL: é administrar uma janela de comportamentos simultâneos.
Uma versão só terminou de ser publicada quando o ecossistema voltou a um estado previsível.
Separe contrato, implementação e implantação
O contrato diz o que consumidores podem esperar. A implementação diz como o servidor entrega esse comportamento. A implantação define quando cada participante passa a usá-lo. Misturar as três coisas faz uma alteração local se transformar em publicação coordenada de todo o ecossistema.
Prefira mudanças aditivas
Adicionar um campo opcional, aceitar dois formatos durante a transição e introduzir um endpoint sem remover o anterior são mudanças mais seguras. Alterar significado, tornar obrigatório ou reutilizar um campo para outra finalidade são mudanças destrutivas, mesmo quando o JSON continua válido.
- Documente o comportamento, não apenas o formato.
- Defina valores padrão para consumidores antigos.
- Faça leitores tolerantes e escritores consistentes.
- Registre a versão ou capacidade efetivamente usada.
Use capacidade quando a versão não basta
Um número de versão informa uma posição no tempo, mas nem sempre descreve o que o cliente suporta. Em transições longas, negociação de capacidades pode ser mais clara: o cliente declara recursos conhecidos e o servidor responde dentro daquele conjunto.
Isso evita condicionais espalhadas como “se versão maior que X” e aproxima o código da pergunta correta: este participante entende o novo comportamento?
Planeje a retirada antes de publicar
Compatibilidade sem prazo vira acúmulo permanente. Toda transição deve nascer com critério de observação e retirada: quais consumidores ainda usam o contrato antigo, como serão identificados, quando a cobertura é suficiente e qual reversão existe caso a nova versão falhe.
- Publicar suporte simultâneo.
- Observar adoção por consumidor e operação.
- Comunicar e concluir a migração dos remanescentes.
- Remover o comportamento antigo com uma mudança própria.
Versionamento eficaz reduz coordenação obrigatória. Quando cada parte pode evoluir em seu ritmo sem perder previsibilidade, a arquitetura passa a servir à operação — e não o contrário.