Versioning

This topic describes the versioning strategies used by Google APIs. In general, these strategies apply to all Google-managed services.

Sometimes it is necessary to make backwards-incompatible (or "breaking") changes to an API. These kinds of changes can cause issues or breakage for code that has dependencies on the original functionality.

Google APIs use a versioning scheme to prevent breaking changes. Additionally, Google APIs make some functionality only available under certain stability levels , such as alpha and beta components.

Guidance

All Google API interfaces mustprovide a major version number , which is encoded at the end of the protobuf package, and included as the first part of the URI path for REST APIs. If an API introduces a breaking change, such as removing or renaming a field, it mustincrement its API version number to ensure that existing user code does not suddenly break.

A new major version of an API must notdepend on a previous major version of the same API. An API maydepend on other APIs, with an expectation that the caller understands the dependency and stability risk associated with those APIs. In this scenario, a stable API version mustonly depend on stable versions of other APIs.

Different versions of the same API mustbe able to work at the same time within a single client application for a reasonable transition period. This time period allows the client to transition smoothly to the newer version. An older version mustgo through a reasonable, well-communicated deprecation period before being shut down.

For releases which have alpha or beta stability , APIs mustappend the stability level after the major version number in the protobuf package and URI path using one of these strategies:

Channel-based versioning (recommended)
Release-based versioning
Visibility-based versioning

Channel-based versioning

A stability channel is a long-lived release at a given stability level that receives in-place updates. There is no more than one channel per stability level for a major version. Under this strategy, there are up to three channels available: alpha, beta, and stable.

The alpha and beta channel musthave their stability level appended to the version, but the stable channel must nothave the stability level appended. For example, v1 is an acceptable version for the stable channel, but v1beta or v1alpha are not. Similarly, v1beta or v1alpha are acceptable versions for the respective beta and alpha channel, but v1 is not acceptable for either. Each of these channels receives new features and updates "in-place".

The beta channel's functionality mustbe a superset of the stable channel's functionality, and the alpha channel's functionality mustbe a superset of the beta channel's functionality.

Deprecating API functionality

API elements (fields, messages, RPCs) maybe marked deprecated in any channel to indicate that they should no longer be used:

  // Represents a scroll. Books are preferred over scrolls. 
 message 
  
 Scroll 
  
 { 
  
 option 
  
 deprecated 
  
 = 
  
 true 
 ; 
  
 // ... 
 }

Deprecated API functionality must notgraduate from alpha to beta, nor beta to stable. In other words, functionality must notarrive "pre-deprecated" in any channel.

The beta channel's functionality maybe removed after it has been deprecated for a sufficient period; we recommend 180 days. For functionality that exists only in the alpha channel, deprecation is optional, and functionality maybe removed without notice. If functionality is deprecated in an API's alpha channel before removal, the API shouldapply the same annotation, and mayuse any timeframe it wishes.

Release-based versioning

An individual release is an alpha or beta release that is expected to be available for a limited time period before its functionality is incorporated into the stable channel, after which the individual release will be shut down. When using release-based versioning strategy, an API may have any number of individual releases at each stability level.

Alpha and beta releases musthave their stability level appended to the version, followed by an incrementing release number. For example, v1beta1 or v1alpha5 . APIs shoulddocument the chronological order of these versions in their documentation (such as comments).

Each alpha or beta release maybe updated in place with backwards-compatible changes. For beta releases, backwards-incompatible updates shouldbe made by incrementing the release number and publishing a new release with the change. For example, if the current version is v1beta1 , then v1beta2 is released next.

Alpha and beta releases shouldbe shut down after their functionality reaches the stable channel. An alpha release maybe shut down at any time, while a beta release shouldallow users a reasonable transition period; we recommend 180 days.

Visibility-based versioning

API visibility is an advanced feature provided by Google API infrastructure. It allows API producers to expose multiple external API views from one internal API surface, and each view is associated with an API visibility label , such as:

  import 
  
" google 
 / 
 api 
 / 
 visibility.proto 
" ; 
 message 
  
 Resource 
  
 { 
  
 string 
  
 name 
  
 = 
  
 1 
 ; 
  
 // Preview. Do not use this feature for production. 
  
 string 
  
 display_name 
  
 = 
  
 2 
  
 [( 
 google.api.field_visibility 
 ) 
 . 
 restriction 
  
 = 
  
" PREVIEW 
" ]; 
 }

A visibility label is a case-sensitive string that can be used to tag any API element. By convention, visibility labels should always use UPPER case. An implicit PUBLIC label is applied to all API elements unless an explicit visibility label is applied as in the example above.

Each visibility label is an allow-list. API producers need to grant visibility labels to API consumers for them to use API features associated with the labels. In other words, an API visibility label is like an ACL'ed API version.

Multiple visibility labels maybe applied to an element by using a comma-separated string (e.g. "PREVIEW,TRUSTED_TESTER" ). When multiple visibility labels are used, then the client needs only one of the visibility labels (logical OR ).

A single API request can only use one visibility label. By default, the visibility label granted to the API consumer is used. A client can send requests with an explicit visibility label as follows:

  GET 
 /v1/projects/my-project/topics 
 HTTP 
 / 
 1.1 
 Host 
 : 
 pubsub.googleapis.com 
 Authorization 
 : 
 Bearer y29.... 
 X-Goog-Visibilities 
 : 
 PREVIEW

API producers can use API visibility for API versioning, such as INTERNAL and PREVIEW . A new API feature starts with the INTERNAL label, then moves to the PREVIEW label. When the feature is stable and becomes generally available, all API visibility labels are removed from the API definition.

In general, API visibility is easier to implement than API versioning for incremental changes, but it depends on sophisticated API infrastructure support. Google Cloud APIs often use API visibility for Preview features.

Using proto3

Compatibility