Versioning an API

This page provides detailed configuration and deployment procedures for changing the version number of your API. The procedure that you use depends on whether the changes to your API are backwards compatible.

For additional information and best practices, see API lifecycle management.

Backwards-compatible changes

When you have made changes to your API that are backwards compatible with the existing client code, as a best practice, increment the minor version number of your API before you deploy the new version. Although Cloud Endpoints runs only one minor version of an API at a time, the graphs and logs in the Cloud Endpoints dashboard display the version number. By incrementing the minor version number before you deploy, the graphs and logs in the Cloud Endpoints dashboard provide a labeled history of your deployments.

To increment the minor version number:

  1. In openapi.yaml, increment the minor version number of the info.version field. For example, if the current version is 1.1, set info.version to 1.2:

    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.2"
    host: "echo-api.endpoints.example-project.cloud.goog"
    
  2. Use the gcloud command-line tool to deploy the API configuration:

    gcloud endpoints services deploy openapi.yaml
    
  3. Deploy the API backend using the configuration ID returned from the previous step. For details, see Deploying and Redeploying an API.

Backwards-incompatible changes

When you have made changes to your API that would break your customers' client code, as a best practice, increment the major version number of your API. Cloud Endpoints can run more than one major version of an API concurrently. By providing both versions of the API, your customers can pick which version they want to use and control when they migrate to the new version.

To run the existing and new versions of an API concurrently:

  1. Create separate OpenAPI configuration files for each version you need to serve. This procedure uses the file names openapi-v1.yaml and openapi-v2.yaml for example purposes.

  2. Copy the contents of openapi-v1.yaml to openapi-v2.yaml.

  3. In openapi-v1.yaml configure the following:

    • Set the info.version field to the existing version number.
    • Leave the basePath field unchanged.

For example:

    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.1"
    host: "echo-api.endpoints.example-project.cloud.goog"
    basePath: "/v1"
  1. In openapi-v2.yaml configure the following:

    • Set the info.version field to the new version number.
    • Set the basePath field to include the new major version number.

    For example:

    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "2.0"
    host: "echo-api.endpoints.example-project.cloud.goog"
    basePath: "/v2"
    
  2. Use the gcloud command-line tool to deploy both API configuration files:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml
    
  3. Deploy a single backend that serves both versions of the API using the configuration ID returned from the previous step. For details, see Deploying and Redeploying an API.

See also:

Send feedback about...

Cloud Endpoints with OpenAPI