Evolução compatível, migrações explícitas.
A versão principal fica na URL. Mudanças aditivas entram em v1 sem quebrar clientes; mudanças incompatíveis exigem uma nova versão e janela de migração.
O que pode mudar em v1
Operações e recursos adicionais podem ser publicados.
Clientes devem ignorar propriedades desconhecidas em respostas.
Assinaturas com * podem receber tipos adicionados ao catálogo.
Enums abertos podem ganhar estados ou provedores documentados.
O que exige nova versão
Endpoint, campo ou valor existente não desaparece silenciosamente.
Semântica, unidade ou formato incompatível exige contrato novo.
Um campo opcional não passa a obrigatório dentro da mesma versão.
Mudanças incompatíveis de autorização recebem migração própria.
Ciclo de depreciação
A mudança entra no histórico com substituição e impacto.
As duas formas convivem durante a janela informada.
Documentação e respostas identificam o contrato descontinuado.
A remoção acontece somente na data anunciada.