Necesitas hacer un cambio incompatible en una API pública. ¿Cómo la versionas y retiras el comportamiento antiguo?

Primero comprueba si de verdad tiene que romper: añadir campos y aceptar parámetros opcionales es compatible hacia atrás si los clientes ignoran los campos desconocidos. Si de verdad rompe, versiona de forma explícita, normalmente con un prefijo de ruta para las versiones mayores, mantén ambas versiones en paralelo contra un único modelo interno, publica un calendario de deprecación con cabeceras y métricas por versión, y elimina la antigua solo cuando su tráfico sea prácticamente cero.

Mi primer movimiento es comprobar si hace falta romper. Añadir un campo, añadir un parámetro opcional, añadir un valor de enum si los clientes toleran lo desconocido, todo eso sale sin subir de versión. Romper significa quitar o renombrar un campo, endurecer la validación o cambiar el significado de un valor existente. Cuando de verdad rompe, uso una versión mayor en la ruta, porque se ve en los logs y es fácil de razonar para los clientes, y mantengo la versión antigua como una capa fina de traducción sobre el mismo modelo interno para no mantener dos implementaciones. Después viene lo que de verdad lleva tiempo: instrumentar peticiones por versión y por cliente, publicar una fecha de retirada en una cabecera de respuesta y en la documentación, y contactar directamente con quienes más llaman. En la última que hice, el tráfico a v1 bajó a un puñado de peticiones al día desde dos integraciones, hablamos con ellos y fue seguro eliminarla tres meses después. Sin métricas por cliente nunca llegas a borrar nada.