Versionado
Qué cambios son compatibles dentro de /v1 y cómo se publican los incompatibles.
La versión va en la ruta: todas las rutas actuales empiezan con /v1. Dentro de una versión solo hacemos cambios compatibles hacia atrás:
- se agregan campos nuevos en las respuestas (tu cliente debe ignorar los campos que no conozca);
- se agregan parámetros opcionales, valores de enumeración y endpoints nuevos;
- nunca se eliminan campos ni cambian de tipo, y no se vuelven obligatorios parámetros que antes eran opcionales.
Los cambios incompatibles se publican como una nueva versión (/v2) con un periodo de convivencia anunciado con anticipación, durante el cual /v1 sigue funcionando.
Las novedades de cada versión se publican en el registro de cambios.