Gestionar las versiones de APIs

En esta página se describen los procedimientos detallados de configuración e implementación para cambiar el número de versión de tu API. El procedimiento que utilices dependerá de si los cambios en tu API son retrocompatibles.

Para obtener más información y consultar las prácticas recomendadas, consulta Gestión del ciclo de vida de las APIs.

Cambios retrocompatibles

Cuando hagas cambios en tu API que sean compatibles con versiones anteriores del código de cliente, te recomendamos que aumentes el número de versión secundaria de tu API antes de implementar la nueva versión. Aunque Cloud Endpoints solo ejecuta una versión secundaria de una API a la vez, los gráficos y los registros de Endpoints > Services muestran el número de versión. Si aumentas el número de versión secundaria antes de implementar, los gráficos y los registros proporcionarán un historial etiquetado de tus implementaciones.

Para aumentar el número de versión secundaria, haz lo siguiente:

  1. En openapi.yaml, aumenta el número de versión secundaria del campo info.version. Por ejemplo, si la versión actual es 1.1, define info.version como 1.2:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Usa la CLI de Google Cloud para desplegar la configuración de la API:

    gcloud endpoints services deploy openapi.yaml

  3. Despliega el backend de la API con el ID de configuración que has obtenido en el paso anterior. Para obtener más información, consulta Implementar el backend de la API.

Cambios incompatibles con versiones anteriores

Cuando hagas cambios en tu API que afecten al código de cliente de tus clientes, te recomendamos que aumentes el número de versión principal de tu API. Los endpoints pueden ejecutar más de una versión principal de una API simultáneamente. Al proporcionar ambas versiones de la API, tus clientes pueden elegir la que quieran usar y controlar cuándo migran a la nueva versión.

Para ejecutar las versiones antigua y nueva de una API simultáneamente, sigue estos pasos:

  1. Crea archivos de configuración de OpenAPI independientes para cada versión que necesites publicar. En este procedimiento, se usan los nombres de archivo openapi-v1.yaml y openapi-v2.yaml a modo de ejemplo.

  2. Copia el contenido de openapi-v1.yaml en openapi-v2.yaml.

  3. En openapi-v1.yaml, configure lo siguiente:

    • Asigne al campo info.version el número de versión actual.
    • Deja el campo basePath sin modificar.

    Por ejemplo:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. En openapi-v2.yaml, configure lo siguiente:

    • Hacer cambios incompatibles con versiones anteriores.
    • Asigna al campo info.version el nuevo número de versión.
    • Define el campo basePath para que incluya el nuevo número de versión principal.
    • Elimina la sección x-google-endpoints. Esta sección es necesaria si quieres especificar una dirección IP de DNS o la marca allowCors. Cuando se despliegan dos versiones de la API con dos archivos de configuración YAML, solo una de ellas puede tener x-google-endpoints, pero su configuración se aplicará a ambas versiones.

    Por ejemplo:

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. Usa la CLI de Google Cloud para desplegar ambos archivos de configuración de la API:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. Despliega un único backend que sirva ambas versiones de la API mediante el ID de configuración devuelto en el paso anterior. Para obtener más información, consulta Implementar el backend de la API.

Siguientes pasos