Gobierno de APIs – Versionamiento de un API

El versionado de servicios es una práctica por la cual, al producirse un cambio en el API de un servicio (no tiene por qué ser únicamente un API REST), se libera una nueva versión de ese servicio de manera que la versión nueva y la anterior conviven durante un periodo de tiempo.

De esta manera, los clientes irán migrando a la nueva versión del API de manera secuencial. Cuando todos los clientes estén consumiendo la última versión del API, se retira la anterior.

Step 1: Antes de nada lo que haremos será asegurarnos de que versionamos de manera independiente el API de un servicio y su correspondiente servicio de backend (lógica funcional que encapsula)

Step 2: Cuando se produce un cambio en el API del servicio, lo siguiente que hacemos es liberar una nueva versión del servicio con su correspondiente nueva versión del API y lógica de backend. Una vez liberada la nueva versión, avisamos a los consumidores del servicio indicando que existe una nueva versión disponible.

Step 3: Una vez dado el aviso a los consumidores, éstos se van adaptando para consumir la nueva versión del servicio.

Step 4: Y llega un punto en el que todos nuestros consumidores están consumiendo la última versión del servicio. Una vez que ya tenemos a todos los consumidores utilizando la última versión del API del servicio, retiramos la versión antigua.

¿Y por qué todo esto? Pues muy sencillo, porque los servicios cambian, es inevitable. Cambia el contrato (API) y cambia la implementación. El objetivo de todo esto es minimizar el impacto del cambio del contrato.

Para que los clientes puedan distinguir entre una versión u otra del servicio, se suelen utilizar un cambio en el path

Añadir la versión del API el contexto de la URL base de nuestra API. Recomiendo por practicidad, además de la más utilizada en las principales APIs de referencia. Similar a esto:

Versión 1: http://host:puerto/api/<api-name>/v1/<operation-name>

Versión 2: http://host:puerto/api/<api-name>/v2/<operation-name>