En esta página, se describe cómo realizar el control de versiones de tu API y cómo implementarlo en varias versiones.
Recomendaciones para administrar versiones de API
Cuando administres tus versiones de API, ten en cuenta estas recomendaciones:
- Cuando desees introducir un cambio incremental, pero no rotundo, mantén la versión de la API constante e impleméntala sobre la API existente.
- Cuando ingresas un cambio rotundo en tu API, incrementa la versión de la API.
- Para obtener protección adicional, incrementa también la versión de la aplicación de App Engine y, luego, implementa la nueva versión de la API en esa nueva versión de la aplicación de App Engine. Esto te permite usar la flexibilidad incorporada de App Engine para cambiar de forma rápida entre las versiones de App Engine y entregar desde las versiones de trabajo anteriores si tienes problemas inesperados.
En la siguiente tabla, se ilustran las versiones de la API de backend en cascada para diferentes versiones de la aplicación de App Engine.
| Versión de la aplicación | Versión de la API de backend |
|---|---|
| 1 |
|
| 2 |
|
| 3 |
|
Como se muestra en la tabla, se implementan actualizaciones incrementales y no rotundas hasta la v1 de la API, cada una de las cuales reemplaza la versión anterior. Cuando se ingresan cambios rotundos, la versión de la API se incrementa a la v2 y se implementa en una nueva versión de la aplicación de App Engine. Esto te permite volver a la versión anterior de la aplicación si es necesario.
En la tabla, observa que la versión 2 de la aplicación es compatible con la última versión v1 y la versión v2 nueva de tu API. Si no borras el código de la v1 existente de tu proyecto, implementarlo provocará que la v2 y la vl (n) de tu API se implementen en la versión 2 de la aplicación.
Implementa en varias versiones de aplicación
Cuando implementas la API de backend, la implementas en el ID del proyecto de Google Cloud que creaste para la API y, además, debes especificar la versión de App Engine en la que la implementas.
Debes especificar la versión de la app de App Engine en el elemento <version> del archivo /WEB-INF/appengine-web.xml. La versión de la app de App Engine no es lo mismo que el número de versión de la API de backend, que se especifica en el atributo version de la anotación @Api.
Como se muestra en la figura anterior, puedes implementar varias versiones de API en la misma versión de App Engine. Además, puedes tener muchas versiones de App Engine para una aplicación.
Acceder a las versiones de la API implementadas en una versión en uso
La primera versión de App Engine en la que implementas tu API es la versión en uso. Esta se ejecuta en la URL http://YOUR_PROJECT_ID.appspot.com, en la que YOUR_PROJECT_ID representa el ID del proyecto de Google Cloud. Puedes acceder a todas las versiones de API implementadas en esa versión de la aplicación de App Engine mediante esa URL.
La versión en uso permanece igual hasta que la cambies explícitamente en la consola de Google Cloud.
Accede a las versiones de la API implementadas en una versión de aplicación que no está en uso
Si necesitas acceder a versiones de API que no se implementan en la versión de App Engine que está en uso, emplea una URL específica de la versión, similar a la siguiente:
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
Reemplaza VERSION por tu versión de App Engine y YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud. Por ejemplo, supongamos que tu versión en uso de App Engine es la 1, pero quieres acceder a una versión de la API implementada en la versión 2. Se usaría esta URL: https://2-dot-YOUR_PROJECT_ID.appspot.com.
Para obtener más detalles, consulta la documentación de App Engine.
Acceder a las versiones de la API implementadas en servicios que no están en uso (antes, módulos)
Si necesitas acceder a versiones de API que no se implementan en el servicio predeterminado de App Engine, puedes usar una URL específica del servicio mediante la sintaxis de puntos de la siguiente manera:
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
Para obtener más detalles, consulta la documentación de App Engine.