Administración del ciclo de vida de la API

En esta página se describen las características de control de versiones de la API de Cloud Endpoints, y se proporcionan prácticas recomendadas para el control de versiones y la etapa de pruebas de la API de Endpoints. La información de esta página se aplica a las API que usan la especificación de OpenAPI. En el caso de las API que usan Cloud Endpoints Frameworks para el entorno estándar de App Engine, consulta Administrar el control de versiones de la API: Java o Administrar el control de versiones de la API: Python.

Te recomendamos que sigas los mismos principios básicos que usa Google para el control de versiones de la API y la etapa de pruebas de servicios:

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

    • Configura el número de versión en el campo info.version. Te recomendamos que uses una string de versión que incluya una versión principal y una secundaria, por ejemplo, 1.0.
    • Configura el campo basePath para incluir el número de la versión principal. Te recomendamos usar una ruta de acceso base con un formato dado por la letra v seguida del número de la versión principal, por ejemplo, /v1.

  • Cuando necesites realizar un cambio retrocompatible, como agregar un método nuevo, aumenta el número de versión menor (1.2, 1.3, etc.) en el campo info.version y vuelve a implementarlo. Consulta Control de versiones de una API para obtener más detalles.

  • Cuando necesites realizar un cambio en un método existente que causa errores en el código del cliente, haz una copia de tu 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 tus archivos de configuración de OpenAPI y vuelve a implementar el backend, que ahora tiene ambas versiones del método. Consulta Control de versiones de una API para obtener más detalles.

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

    • Simplifica el enrutamiento porque las solicitudes a una versión específica se basan en la ruta, como en el ejemplo anterior.
    • Simplifica la configuración y también la implementación, dado que usas el mismo backend y proyecto de Google Cloud para todas las versiones principales de la API y, además, implementas todas las versiones de tu API al mismo tiempo.
    • Mantiene tus costos bajos, ya que evita ejecutar backends superfluos.

  • Habilita a etapa tu API en un proyecto separado de Google Cloud antes de implementarla en tu proyecto de producción de Google Cloud. Consulta Servicios de etapa de pruebas para obtener más detalles.

El uso de números de versiones principales y secundarios en Endpoints corresponde a las definiciones en Control de versiones semánticas. Aunque Endpoints no requiere que aumentes el número de versión del parche en tu archivo de configuración de OpenAPI ni que implementes la configuración cuando implementas una corrección de errores en tu código de backend, puedes elegir hacerlo si así lo deseas.

Características del control de versiones de la API de Cloud Endpoints

El Proxy de servicio extensible (ESP) puede administrar varias versiones principales de tu API simultáneamente en un único proyecto y backend de Google Cloud, siempre que las API no tengan rutas de acceso superpuestas. Por ejemplo:

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

Esto les permite a tus clientes seleccionar qué versión desean usar y controlar cuándo migrar a la versión nueva. El ESP etiqueta cada solicitud con el número de versión antes de su enrutamiento al método aplicable en el backend. Debido a que cada solicitud se marca con un número de versión:

  • Los grafos y registros en Endpoints > Servicios muestran las solicitudes de cada versión principal de la API y el agregado total de todas las versiones. Puedes filtrar la vista para un versión específica. Esto te ofrece una idea clara de cuánto tráfico recibe cada versión. Los registros incluso pueden decirte qué cliente está usando cada versión.

  • Cuando vuelves a implementar tu API con una actualización del número de versión secundario, la actividad posterior es etiquetada con el número de versión nuevo en los grafos y registros. Esto te proporciona un historial etiquetado de tus implementaciones.

  • Cuando quitas una versión de una API, los grafos y registros continúan mostrando datos en el intervalo de tiempo en el que la API estuvo activa.

Ejemplo del ciclo de vida de la API

En esta sección se describe la evolución típica de un servicio.

Versión 1

Inicialmente, implementas la versión 1 del servicio de la API My Awesome Echo. La API se entrega desde my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. En los grafos y registros de Endpoints > Servicios, ves todo el tráfico en 1.0.

Versión 1.1

Tu cliente solicita una característica nueva, por lo tanto, agregas un método nuevo. En tu archivo de configuración de OpenAPI, debes agregar el nuevo método y aumentar el campo info.version a 1.1. Aumentas el número de versión secundario, porque este cambio no causa errores en el código del cliente. Implementas y pruebas tu cambio en un entorno de etapa de pruebas para asegurarte de que funciona.

Luego, implementas la configuración de OpenAPI y el backend de la API en el entorno de producción. La API todavía se entrega desde my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, pero ahora los emisores pueden realizar solicitudes al método nuevo. Debido a que no cambiaste la interfaz a los métodos anteriores, tus clientes no necesitan cambiar y volver a implementar sus clientes; estos pueden continuar enviando solicitudes al método anterior igual que antes.

En Endpoints > Servicios, la versión 1.1 es la que entrega ahora el tráfico. Si seleccionas un intervalo de tiempo anterior, en los grafos y registros se muestra la versión anterior, lo que proporciona un historial etiquetado de tus implementaciones.

Versión 2.0

Con el tiempo, te das cuenta que necesitas realizar un cambio incompatible con las versiones anteriores en un método existente. Debido a que es importante no causar errores en el código del cliente de tus clientes, decides mantener dos versiones de la API. Dejas el método anterior tal como está y, luego, implementas la versión nueva del método. Creas otro archivo de configuración de OpenAPI para la versión 2.0 y configuras la versión nueva a fin de que se entregue desde my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Tu archivo de configuración original de OpenAPI aún se dirige a la versión anterior del método, mientras que el archivo de configuración nuevo de OpenAPI se dirige a la versión nueva del método.

Implementas los archivos de configuración de OpenAPI versión 1 y versión 2 al mismo tiempo, y vuelves a implementar el backend, que ahora contiene ambas versiones del método. (Consulta Control de versiones de la API para obtener más detalles).

Después de la implementación, Endpoints > Servicios muestra que estás entregando dos versiones de tu API, y puedes ver cuánto tráfico recibe cada versión. Los clientes de la v1 pueden seguir llamando a la /v1, pero también pueden llamar a la /v2 para usar la versión nueva del método. La manera en la que tratas el control de versiones en tu código de backend depende del marco de trabajo de la API que uses. Si deseas ver un ejemplo de uso de servlets, consulta Endpoints y Java con múltiples versiones de muestra.

Inhabilita la versión 1

Con el tiempo, a medida que tus clientes migren y que veas que todo el tráfico en v1 ha parado, puedes dejar de entregarla. Para quitar la versión 1 de tu API, implementa solo el archivo de configuración de OpenAPI de la versión 2 y vuelve a implementar el backend. Ahora puedes quitar de forma segura el código que implementó la versión 1 de tu backend. Endpoints > Servicios conserva los datos históricos de la versión 1.x.

Servicios de etapa de pruebas

Como recomendación, te aconsejamos que habilites etapas para las actualizaciones de tu servicio de Endpoints a fin de que puedas probar el servicio antes de que llegue a tus clientes. También te recomendamos crear un proyecto de Google Cloud separado para la etapa de pruebas de tu servicio, de modo que quede aislado de la producción. Por ejemplo, las cuotas de Google, generalmente, se comparten con los recursos dentro de un mismo proyecto. Por lo tanto, si pones el servicio de etapa de pruebas en el mismo proyecto que el servicio de producción, un error de bucle, por ejemplo, podría causar una interrupción en todo tu servicio de producción.

Te recomendamos crear un nombre de proyecto de Google Cloud que indique claramente que es para la etapa de pruebas. Una estrategia común para asignar este nombre consiste en usar el mismo nombre del proyecto de Google Cloud en producción, pero con -staging al final. También puedes agregar -prod en los proyectos de producción para dejar en claro que el proyecto contiene servicios de producción.

Los nombres de los servicios de Google Cloud deben ser únicos. Debido a que especificas el nombre del servicio en el archivo de configuración de OpenAPI, debes mantener los archivos de configuración de la API separados para proyectos de etapa de pruebas y producción, o usar un conjunto de archivos de configuración de API y definir un proceso en el que cambias el nombre del servicio para que coincida con el nombre del proyecto en el que quieres implementar el servicio.

¿Qué sigue?