Você precisa fazer uma mudança que quebra compatibilidade numa API pública. Como você versiona e aposenta o comportamento antigo?

Primeiro cheque se precisa mesmo quebrar: adicionar campos e aceitar parâmetros opcionais é retrocompatível se os clientes ignoram campos desconhecidos. Se realmente quebra, versione explicitamente, normalmente com um prefixo no path para versões maiores, rode as duas versões lado a lado sobre um único modelo interno, publique um cronograma de descontinuação com headers e métricas por versão, e só remova a antiga quando o tráfego para ela for praticamente zero.

Meu primeiro movimento é checar se aquilo precisa quebrar. Adicionar um campo, adicionar um parâmetro opcional, adicionar um valor de enum se os clientes toleram desconhecidos, tudo isso vai para produção sem subir versão. Quebrar significa remover ou renomear um campo, apertar a validação ou mudar o significado de um valor existente. Quando realmente quebra, eu uso uma versão maior no path, porque fica visível nos logs e é fácil para os clientes raciocinarem sobre, e mantenho a versão antiga como uma camada fina de tradução sobre o mesmo modelo interno, para não manter duas implementações. Depois vem a parte que realmente toma tempo: instrumentar requisições por versão e por cliente, publicar uma data de encerramento num header de resposta e na documentação, e falar diretamente com quem mais chama. Na última que conduzi, o tráfego da v1 caiu para um punhado de requisições por dia vindas de duas integrações, entramos em contato, e três meses depois deu para remover com segurança. Sem métricas por cliente você nunca consegue apagar nada.