Control de versiones de una API

En esta página, se proporcionan procedimientos detallados de configuración y de implementación para cambiar el número de versión de tu API. El procedimiento que debes usar depende de si los cambios en la API son retrocompatibles.

Si deseas obtener información adicional y recomendaciones, consulta Administración del ciclo de vida de la API.

Cambios compatibles con las versiones anteriores

Cuando realizas cambios en tu API que son retrocompatibles con el código de cliente existente, te recomendamos que aumentes el número de la versión secundaria de la API antes de implementar la versión nueva. Aunque Cloud Endpoints ejecuta solo una versión secundaria de una API a la vez, los grafos y registros en Endpoints > Servicios muestran el número de versión. Cuando aumentas el número de versión secundario antes de implementar, los grafos y registros proporcionan un historial etiquetado de tus implementaciones.

Para aumentar el número de versión secundario, sigue estos pasos:

  1. En openapi.yaml, aumenta el número de versión menor del campo info.version. Por ejemplo, si la versión actual es 1.1, configura 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 Google Cloud CLI para implementar la configuración de la API:

    gcloud endpoints services deploy openapi.yaml

  3. Implementa el backend de la API mediante el ID de configuración que se mostró en el paso anterior. Si deseas obtener más detalles, consulta Cómo implementar el backend de la API.

Cambios incompatibles con las versiones anteriores

Cuando realizas cambios en tu API que rompen el código del cliente, te recomendamos que aumentes el número de versión principal de la API. Endpoints puede ejecutar más de una versión principal de la API a la vez. Si proporcionas ambas versiones de la API, tus clientes pueden seleccionar qué versión desean usar y controlar cuándo migrar a la versión nueva.

Para ejecutar la versión nueva y la existente de una API de forma simultánea, sigue estos pasos:

  1. Crea archivos de configuración de OpenAPI separados para cada versión que necesites entregar. Este procedimiento usa los nombres de archivo openapi-v1.yaml y openapi-v2.yaml para fines de ejemplo.

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

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

    • Establece el campo info.version en el número de versión existente.
    • 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, configura lo siguiente:

    • Realiza cambios incompatibles con las versiones anteriores.
    • Establece el campo info.version en el número de versión nuevo.
    • Establece el campo basePath para que incluya el número de la versión principal nueva.
    • Quita la sección x-google-endpoints. Esta sección es necesaria si deseas especificar una dirección IP de DNS o una marca allowCors. Cuando implementas dos versiones de la API con dos archivos de configuración yaml, solo uno de ellos 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 Google Cloud CLI para implementar ambos archivos de configuración de la API:

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

  6. Implementa un único backend que entregue ambas versiones de la API mediante el ID de configuración que se mostró en el paso anterior. Si deseas obtener más detalles, consulta Cómo implementar el backend de la API.

¿Qué sigue?