Versionamiento del API

El API debe permitir la especificación de una versión sobre la cual se pueden consumir la información de Evolution.

Política de versionamiento

La política de versionamiento será la siguiente:

1. La nomenclatura de la versión está definida utilizando dos grupos de dígitos (##.##), el primer grupo representará la versión mayor o principal y el segundo grupo será la versión menor o revisión.

2. Puede aumentar el segundo grupo, cuando se introducen cambios en el API pero que no causan ningún "breaking change", es decir, que un cliente preparado para acceder a la version 1.0, también podrá acceder a la versión 1.1, sin requerir cambios en el código fuente del consumidor del API.

3. Cuando cambie el primer grupo de dígitos, será porque se introducen "breaking changes" que obligan al cliente a modificar su código fuente para poder consumir la nueva versión.

4. Un cliente que consume el API, puede o no enviar la versión sobre la cual desea fijar su consulta. Si no la envía entonces el API decidirá retornar los datos que corresponden a la que tiene configurada por defecto, es decir, la más reciente. Por lo tanto un consumidor podría seguir consultando el API incluso si la versión principal cambia, siempre y cuando no utilice los endpoints afectados por el "breaking change".

5. Todos los endpoints publicados por el API retornaran los datos con la estructura de la versión que se envía en la consulta. Esto quiere decir que en muchos casos será posible continuar consultando los datos en versiones anteriores. Cuando por la naturaleza del cambio ya no fuera posible mantener esta retrocompatibilidad, el endpoint será marcado con la versión que soporta y las versiones anteriores serán marcadas como "obsoletas" y se requerirá que el consumidor modifique su código fuente para adaptarse a la nueva estructura de los datos.

Convención para el envío de la versión

Si se desea especificar la versión del API que se desea consultar, el consumidor tiene dos formas de hacerlo:

Enviando la versión en un Request Header

Para utilizar el mecanismo de Request Header se necesita un producto como Postman o similar para poder especificar en la lista de Request Headers la llave "x-api-version" y en el valor el número de versión.

Enviando la versión en el QuerString

Para utilizar el mecanismo en el QueryString basta con especificarlo junto a la URL

GET /api/v1/plazas/345?api-version=1.0

Este key “api-version=1.0" determina que queremos los datos en la estructura de la versión 1.0.