Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
OpenAPI | gRPC
En esta página, se proporcionan procedimientos de implementación y configuración detallados para cambiar el número de versión de tu API. El procedimiento que usas depende de si los cambios en la API son compatibles con las versiones anteriores.
Si la versión nueva de la API tiene cambios compatibles con las versiones anteriores, como agregar campos o métodos nuevos, consulta Cambios compatibles con 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:
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"
Usa Google Cloud CLI para implementar la configuración de la API:
gcloud endpoints services deploy openapi.yaml
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:
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.
Copia el contenido de openapi-v1.yaml en openapi-v2.yaml.
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"
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"
Usa Google Cloud CLI para implementar ambos archivos de configuración de la API:
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.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (UTC)"],[[["\u003cp\u003eThis document outlines procedures for updating API versions, differentiating between backwards-compatible and backwards-incompatible changes.\u003c/p\u003e\n"],["\u003cp\u003eFor backwards-compatible changes, it's recommended to increment the minor version number in the \u003ccode\u003einfo.version\u003c/code\u003e field of the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file and then deploy using the Google Cloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eWhen introducing backwards-incompatible changes, it's recommended to increment the major version number and create separate OpenAPI configuration files for each version.\u003c/p\u003e\n"],["\u003cp\u003eTo deploy multiple major versions concurrently, each version should have its own configuration file (e.g., \u003ccode\u003eopenapi-v1.yaml\u003c/code\u003e, \u003ccode\u003eopenapi-v2.yaml\u003c/code\u003e) with distinct \u003ccode\u003ebasePath\u003c/code\u003e values and the \u003ccode\u003ex-google-endpoints\u003c/code\u003e section removed from all but one configuration.\u003c/p\u003e\n"],["\u003cp\u003eAfter the deployment of the API configuration files, a single backend must be deployed that services both versions of the API.\u003c/p\u003e\n"]]],[],null,["# Versioning an API\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page provides detailed configuration and deployment procedures for changing\nthe version number of your API. The procedure that you use depends on whether\nthe changes to your API are backwards compatible.\n\n- If your new API version has backwards-compatible changes, such as adding new fields or methods, see [Backwards-compatible changes](#backwards-compatible).\n- If your new API has changes to an existing method that breaks your customers' client code, see [Backwards-incompatible changes](#backwards-incompatible).\n\nFor additional information and best practices, see\n[API lifecycle management](/endpoints/docs/openapi/lifecycle-management).\n\nBackwards-compatible changes\n----------------------------\n\nWhen you make changes to your API that are backwards compatible with\nexisting client code, as a best practice, increment the minor version number of\nyour API before you deploy the new version. Although Cloud Endpoints runs only\none minor version of an API at a time, the graphs and logs in\n**Endpoints** \\\u003e **Services** display the version number. By incrementing the\nminor version number before you deploy, the graphs and logs provide a labeled\nhistory of your deployments.\n\nTo increment the minor version number:\n\n1. In `openapi.yaml`, increment the minor version number of the\n `info.version` field. For example, if the current version is `1.1`, set\n `info.version` to `1.2`:\n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.2\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n\n2. Use the Google Cloud CLI to deploy the API configuration:\n\n gcloud endpoints services deploy openapi.yaml\n\n3. Deploy the API backend by using the configuration ID returned from the\n previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nBackwards-incompatible changes\n------------------------------\n\nWhen you make changes to your API that breaks your customers' client\ncode, as a best practice, increment the major version number of your API.\nEndpoints can run more than one major version of an API\nconcurrently. By providing both versions of the API, your customers can pick\nwhich version they want to use and control when they migrate to the new version.\n\nTo run the existing and new versions of an API concurrently:\n\n1. Create separate OpenAPI configuration files for each version you need to\n serve. This procedure uses the file names `openapi-v1.yaml` and\n `openapi-v2.yaml` for example purposes.\n\n2. Copy the contents of `openapi-v1.yaml` to `openapi-v2.yaml`.\n\n3. In `openapi-v1.yaml` configure the following:\n\n - Set the `info.version` field to the existing version number.\n - Leave the `basePath` field unchanged.\n\n For example: \n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.1\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v1\"\n\n4. In `openapi-v2.yaml` configure the following:\n\n - Make backwards-incompatible changes.\n - Set the `info.version` field to the new version number.\n - Set the `basePath` field to include the new major version number.\n - Remove the `x-google-endpoints` section. This section is needed if you want to specify DNS IP address or `allowCors` flag. When deploying two versions of the API with two yaml config files, only one of them can have `x-google-endpoints`, but its config will apply to both versions.\n\n For example: \n\n info:\n description: \"A simple Google Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"2.0\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v2\"\n\n5. Use the Google Cloud CLI to deploy both API configuration files:\n\n gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml\n\n | **Note:** Cloud Endpoints internally converts your multiple OpenAPI configuration files into a single configuration, which is identified by one configuration ID.\n6. Deploy a single backend that serves both versions of the API by using the\n configuration ID returned from the previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nWhat's next\n-----------\n\n- [API lifecycle management](/endpoints/docs/openapi/lifecycle-management)\n- [Planning your Google Cloud projects](/endpoints/docs/openapi/planning-cloud-projects)"]]
