Evolución compatible, migraciones explícitas.
La versión principal está en la URL. Los cambios adicionales entran en la versión 1 sin afectar a los clientes; Los cambios incompatibles requieren una nueva versión y una ventana de migración.
¿Qué podría cambiar en la v1?
Es posible que se publiquen operaciones y funciones adicionales.
Los clientes deben ignorar las propiedades desconocidas en las respuestas.
Las suscripciones con * pueden tener tipos agregados al catálogo.
Las enumeraciones abiertas pueden obtener estados o proveedores documentados.
¿Qué requiere una nueva versión?
El punto final, campo o valor existente no desaparece silenciosamente.
La semántica, unidad o formato incompatible requiere un nuevo contrato.
Un campo opcional no pasa a ser obligatorio dentro de una misma versión.
Los cambios de autorización incompatibles reciben su propia migración.
Ciclo de depreciación
El cambio entra en la historia con reemplazo e impacto.
Las dos formas coexisten durante la ventana informada.
La documentación y las respuestas identifican el contrato discontinuado.
La retirada sólo se realizará en la fecha anunciada.