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
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. If an API introduces a breaking change, such as
removing or renaming a field, it
must
increment its API version number to
ensure that existing user code does not suddenly break.
A new major version of an API
must not
depend on a previous major version of
the same API. An API
may
depend 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
must
only depend on stable versions
of other APIs.
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)
- 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.
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
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
).
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.