Cambios importantes de versión
En el sistema de referencia, esta página documenta la migración de su Web API basada en OData a una nueva versión mayor (cambios de rutas, convenciones OData v4, formato de consultas $filter/$expand, etc.). La Web API de Crono no es OData: es una API REST versionada con Asp.Versioning, por lo que esos cambios concretos no aplican.
Cómo versiona Crono su API
En lugar de una única migración disruptiva, Crono gestiona los cambios mediante versionado por endpoint:
- La versión va en la ruta:
api/v1/...,api/v2/.... - Cada acción declara a qué versión responde con
MapToApiVersion("..."). - Cada grupo de la documentación declara qué versiones expone (por ejemplo, el grupo
comunpublica1y2); ver La Web API en detalle.
Esto permite introducir una versión nueva de un recurso sin romper a los clientes que siguen usando la anterior: ambas conviven hasta que la antigua se retire.
Buenas prácticas al evolucionar la API
- Cambios compatibles (añadir un campo opcional, un endpoint nuevo): pueden ir en la versión actual.
- Cambios incompatibles (renombrar/quitar campos, cambiar tipos o semántica): introduce una versión nueva del endpoint y mantén la anterior mientras haya clientes.
- Comunica y depreca: marca la versión antigua como obsoleta en la documentación antes de retirarla, y da un periodo de transición.
- El tipo de medio (
application/vnd.crono.v1+json) y el modelo de errores se mantienen estables entre versiones para no añadir fricción innecesaria.
Cuando Crono publique una versión mayor de un grupo de la API con cambios incompatibles, aquí se listarán los cambios concretos y la guía de migración para los clientes.