Gestión del ciclo de vida de las APIs

En esta página se describen las funciones de control de versiones de la API de Cloud Endpoints y se ofrecen prácticas recomendadas para controlar las versiones y las fases de tu API de Endpoints. La información de esta página se aplica a las APIs que usan la especificación de OpenAPI. En el caso de las APIs que usan Cloud Endpoints Frameworks para el entorno estándar de App Engine, consulta Gestión de versiones de la API: Java o Gestión de versiones de la API: Python.

Te recomendamos que sigas los mismos principios básicos que Google utiliza para el control de versiones de las APIs y la puesta en marcha de los servicios:

  • Incluye lo siguiente en tu archivo de configuración de OpenAPI antes de desplegar la versión inicial:

    • Define el número de versión en el campo info.version. Te recomendamos que uses una cadena de versión que incluya una versión principal y una versión secundaria; por ejemplo, 1.0.
    • Asigna el valor basePath al campo para incluir el número de versión principal. Te recomendamos que uses una ruta base con el formato de la letra v seguida del número de versión principal. Por ejemplo, /v1.

  • Cuando tengas que hacer un cambio compatible con versiones anteriores, como añadir un método nuevo, aumenta el número de versión secundaria (1.2, 1.3, etc.) en el campo info.version y vuelve a implementar. Consulta más información en el artículo sobre control de versiones de una API.

  • Cuando necesites cambiar un método que afecte al código del cliente, haz una copia del archivo de configuración de OpenAPI y haz los siguientes cambios:

    • Aumenta el número de versión principal (2.0, 3.0, etc.) en el campo info.version.
    • Aumenta el número de versión principal (/v2, /v3, etc.) en el campo basePath.

    Implementa ambas versiones de los archivos de configuración de OpenAPI y vuelve a implementar el backend, que ahora tiene ambas versiones del método. Consulta más información en el artículo sobre control de versiones de una API.

  • Implementa todas las versiones principales de la API en un solo backend. Esta recomendación:

    • Simplifica el enrutamiento, ya que las solicitudes a una versión específica se basan en la ruta, como en el ejemplo anterior.
    • Simplifica la configuración y el despliegue. Utilizas el mismo Google Cloud proyecto y backend para todas las versiones principales de la API, y despliegas todas las versiones de tu API al mismo tiempo.
    • Reduce los costes, ya que evita que se ejecuten back-ends superfluos.

  • Organiza tu API en un Google Cloud proyecto independiente antes de implementarla en tu proyecto de producción Google Cloud . Para obtener más información, consulta Servicios de staging.

El uso de números de versión principal y secundaria en Endpoints se corresponde con las definiciones de versionado semántico. Aunque Endpoints no requiere que aumentes el número de versión del parche en tu archivo de configuración de OpenAPI y que implementes la configuración cuando implementes una corrección de errores en tu código de backend, puedes hacerlo si quieres.

Funciones de control de versiones de la API Cloud Endpoints

El proxy de servicio extensible (ESP) puede gestionar varias versiones principales de tu API simultáneamente en un solo proyecto y backend, siempre que las APIs no tengan rutas superpuestas. Google Cloud Por ejemplo:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

De esta forma, tus clientes pueden elegir qué versión quieren usar y controlar cuándo migran a la nueva versión. El ESP etiqueta cada solicitud con el número de versión antes de enrutarla al método aplicable en el backend. Cada solicitud se etiqueta con un número de versión:

  • Los gráficos y los registros de Endpoints > Services muestran las solicitudes de cada versión principal de la API y el total agregado de todas las versiones. Puedes filtrar la vista para ver una versión específica. De esta forma, sabrá claramente cuánto tráfico recibe cada versión. Los registros pueden incluso indicar qué clientes usan qué versión.

  • Cuando vuelvas a implementar tu API con una actualización del número de versión secundaria, la actividad posterior se etiquetará con el nuevo número de versión en los gráficos y los registros. De esta forma, tendrás un historial etiquetado de tus implementaciones.

  • Cuando eliminas una versión de una API, los gráficos y los registros siguen mostrando datos del periodo en el que la API estaba activa.

Ejemplo de ciclo de vida de una API

En esta sección se describe la evolución habitual de un servicio.

Versión 1

Al principio, implementas la versión 1 del servicio de la API My Awesome Echo. La API se proporciona desde my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. En los gráficos y los registros de Endpoints > Services, se muestra todo el tráfico en 1.0.

Versión 1.1

Tus clientes solicitan una nueva función, así que añades un nuevo método. En el archivo de configuración de OpenAPI, añade el nuevo método e incrementa el campo info.version a 1.1. Incrementa el número de versión secundaria porque este cambio no interrumpe el código del cliente. Despliega y prueba el cambio en un entorno de staging para asegurarte de que funciona.

A continuación, implementa la configuración de OpenAPI y el backend de la API en el entorno de producción. La API sigue sirviéndose desde my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, pero ahora los llamantes pueden hacer solicitudes al nuevo método. Como no has cambiado la interfaz a los métodos antiguos, tus clientes no tienen que cambiar ni volver a implementar sus clientes, sino que pueden seguir enviando solicitudes al método antiguo igual que antes.

En Endpoints (Puntos finales) > Services (Servicios), el tráfico servido ahora está en la versión 1.1. Si seleccionas un periodo anterior, se mostrará la versión anterior en los gráficos y los registros, lo que te proporcionará un historial etiquetado de tus implementaciones.

Versión 2.0

Con el tiempo, te das cuenta de que tienes que hacer un cambio incompatible con versiones anteriores en un método. Como es importante que no rompas el código de cliente de tus clientes, decides mantener dos versiones de la API. Dejas el método antiguo tal cual e implementas la nueva versión. Crea otro archivo de configuración de OpenAPI para la versión 2.0 y configura la nueva versión para que se sirva desde my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. El archivo de configuración de OpenAPI original sigue apuntando a la versión antigua del método, mientras que el nuevo archivo de configuración de OpenAPI apunta a la nueva versión del método.

Implementa los archivos de configuración de OpenAPI de las versiones 1 y 2 al mismo tiempo y vuelve a implementar el backend, que ahora contiene ambas versiones del método. (Consulta Control de versiones de una API para obtener más información).

Después de desplegar la API, en Endpoints > Services se muestra que estás ofreciendo dos versiones de la API y puedes ver cuánto tráfico recibe cada versión. Tus clientes de la versión 1 pueden seguir llamando a /v1, pero también pueden llamar a /v2 para usar la nueva versión del método. La forma de gestionar el control de versiones en el código de backend depende del framework de la API que utilices. Para ver un ejemplo con servlets, consulta Endpoints y Java con varias versiones (ejemplo).

Desactivar la versión 1

Con el tiempo, a medida que tus clientes migren y veas que se ha detenido todo el tráfico a la versión 1, puedes dejar de ofrecerla. Para eliminar la versión 1 de tu API, implementa solo el archivo de configuración OpenAPI de la versión 2 y vuelve a implementar el backend. Ahora puedes quitar de forma segura del backend el código que implementaba la versión 1. Endpoints > Services conserva el historial de datos de la versión 1.x.

Servicios de puesta en escena

Como práctica recomendada, te sugerimos que organices las actualizaciones de tu servicio Endpoints para que puedas probarlo antes de que llegue a tus clientes. También te recomendamos que crees unGoogle Cloud proyecto independiente para poner en marcha tu servicio, de forma que esté aislado del entorno de producción. Por ejemplo, las cuotas de Google suelen compartirse entre los recursos de un proyecto. Por lo tanto, si pones el servicio de staging en el mismo proyecto que el servicio de producción, un bucle for erróneo, por ejemplo, podría provocar una interrupción en el servicio de producción.

Te recomendamos que elijas un nombre de proyecto que indique claramente que es de prueba. Google Cloud Una estrategia de nomenclatura habitual es usar el mismo nombre que el de tu proyecto de producción Google Cloud , pero con -staging al final. También puedes poner -prod en los proyectos de producción para dejar claro que el proyecto contiene servicios de producción.

Los nombres de los servicios en Google Cloud deben ser únicos. Como especificas el nombre del servicio en el archivo de configuración de OpenAPI, debes mantener archivos de configuración de API independientes para los proyectos de staging y de producción, o bien usar un conjunto de archivos de configuración de API y diseñar un proceso en el que cambies el nombre del servicio para que coincida con el nombre del proyecto en el que vas a implementar.

Siguientes pasos