AIP-185

API Versioning

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

Guidance

All Google API interfaces must provide 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. In the event an API needs to make an incompatible change, consult AIP-180 and AIP-181 for necessary steps based on the stability level of the surface in question.

Note: The use of the term "major version number" above is taken from semantic versioning. However, unlike in traditional semantic versioning, Google APIs must not expose minor or patch version numbers. For example, Google APIs use v1, not v1.0, v1.1, or v1.4.2. From a user's perspective, major versions are updated in place with minor/patch equivalent changes, and users receive new functionality without migration.

A new major version of an API must not depend on a previous major version of the same API. An API surface must not depend on other APIs, except for in the cases outlined in AIP-213 and AIP-215.

Different versions of the same API must be 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 must go through a reasonable, well-communicated deprecation period before being shut down.

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

  • Channel-based versioning (recommended)
  • Interface-based versioning
  • 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 must have their stability level appended to the version, but the stable channel must not have 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 must be a superset of the stable channel's functionality, and the alpha channel's functionality must be a superset of the beta channel's functionality.

Deprecating API functionality

API elements (fields, messages, RPCs) may be 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 not graduate from alpha to beta, nor beta to stable. In other words, functionality must not arrive "pre-deprecated" in any channel.

The beta channel's functionality may be 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 may be removed without notice. If functionality is deprecated in an API's alpha channel before removal, the API should apply the same annotation, and may use any timeframe it wishes.

Interface-based versioning

Interface-based versioning (IBV) is a versioning system where API producers can iterate quickly and safely on their APIs, while API consumers can update to new service features on their own schedule.

With IBV, consumers experience a given service's API surface through reliable lenses called API versions, and they can pin to any supported version for backward compatibility. Producers provide continued support for all published versions of their APIs, with explicitly time-bounded previews.

IBV rests on the following principles:

  • Flexible versioning scope: API versioning is scoped as small as a single API interface (an individual resource or group of RPCs), or as large as an entire API service.
  • Element annotations: API elements (RPCs, fields, enum values) are annotated with API version ranges indicating when they exist.
  • Versioned requests: API requests carry a version identifier in a header or query parameter.
  • Co-versioned resources: Resources are co-versioned with the API interfaces through which consumers access them. But producers store resource definitions in a single, version-agnostic representation.

Version designation

API requests under IBV must send the API version identifier using either the X-Goog-Api-Version HTTP header or the $apiVersion URL query parameter.

If no version is specified in a request, behavior depends on configuration: the request may default to a producer-chosen version (often the initial API version for legacy clients), may respect a consumer override, or must be rejected with an error if no default is available.

Stable API versions must be a date in YYYY-MM-DD format, such as 2025-09-04. Preview API versions must follow the format YYYY-MM-DD-preview, such as 2025-03-01-preview. See AIP-184 for more details.

Previews

Preview API versions replace the need for traditional alpha and beta channels. Preview API versions are minted based on a given stable API version and represent a superset of that stable API version functionality, unless foreshadowing a potential incompatible change. See AIP-181 for more on the expected stability of Preview API versions.

Preview API versions are explicitly time-bound in their lifecycle and must not be used for stable releases.

API evolution

Service producers must annotate API elements (RPCs, message fields, enum values) with internal annotations indicating the API version ranges in which these elements exist. These annotations define API screens, which represent version-aware lenses on the API surface.

API screens determine request and response shaping in API proxies, and inform API documentation and API Discovery Documents. Service producers bundle API versions for publication, and releases of Discovery Documents, API documentation, and client libraries are built from these bundles.

Deprecating API functionality

Deprecations and breaking changes are gated by incorporating them in a new API version. Users of existing, unchanged API versions are undisturbed and can plan an upgrade at their own pace. Making changes to existing, non-current versions as well as version-gated incompatible or unsafe changes, are governed by the applicable deprecation policy.

Release-based versioning

Important: This pattern is not commonly used for new services. There are existing services that follow it, but Channel-based Versioning is the preferred mechanism.

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.

Note: Both the channel-based and release-based strategies update the stable version in-place. There is a single stable channel, rather than individual stable releases, even when using the release-based strategy.

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

Each alpha or beta release may be updated in place with backwards-compatible changes. For beta releases, backwards-incompatible updates should be 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 should be shut down after their functionality reaches the stable channel. An alpha release may be shut down at any time, while a beta release should allow 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 may be 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).

By default, the visibility labels granted to the API consumer are used to verify incoming requests. However, 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

A single API request can specify at most one visibility label.

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.