This chapter provides the versioning guidelines for networked APIs. Since one API service may provide multiple API interfaces, the API versioning strategy applies at API interface level, not at the API service level. For convenience, the term APIs refers to API interfaces in the following sections.
Networked APIs should use Semantic Versioning. Given a
MAJOR.MINOR.PATCH, increment the:
MAJORversion when you make incompatible API changes,
MINORversion when you add functionality in a backwards-compatible manner,
PATCHversion when you make backwards-compatible bug fixes.
Different rules apply for specifying the major version number depending on the API version:
- For version 1 (v1) of an API, its major version number should be encoded
in the proto package name, for example
google.pubsub.v1. The major version may be omitted from the proto package if the package contains stable types and interfaces that don't expect to have breaking changes, for example
- For all versions of the API other than v1, the major version number must
be encoded in the proto package name. For example,
For pre-GA releases, such as alpha and beta, it is recommended to append a suffix to the version number. The suffix should consist of the pre-release version name (e.g. alpha, beta), and an optional pre-release version number.
Examples of version progression:
|v1alpha||v1alpha1||The v1 alpha release.|
|v1beta1||v1beta1||The v1 beta 1 release.|
|v1beta2||v1beta2||The second beta release of v1.|
|v1test||v1test||An internal test release with dummy data.|
|v1||v1||The v1 major version, general availability.|
|v1.1beta1||v1p1beta1||The first beta release for minor changes to v1.|
|v1.1||v1||The minor update to v1.1 release.|
|v2beta1||v2beta1||The v2 beta 1 release.|
|v2||v2||The v2 major version, general availability.|
The minor and patch numbers should be reflected in the API configuration and documentation, they must not be encoded in the proto package name.
NOTE: Google API Platform does not natively support minor and patch version at this time. For each major API version, there is only one set of documentation and client libraries. API owners need to manually document them via API documentation and release notes.
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 the understanding of dependency and stability risk associated with those APIs. A stable API version must only depend on the latest stable version of other APIs.
For some period of time, different versions of the same API must be able to work at the same time within a single client application. This is to help the client smoothly transition from the older version to the newer version of the API.
An older API version should only be removed after its deprecation period is over.
Common and stable data types that are shared by many APIs, such as date and time, should be defined in a separate proto package. If a breaking change ever becomes necessary, either a new type name, or a package name with a new major version must be introduced.
Determining what counts as a backwards-compatible change can be difficult.
The lists below are a quick-reference starting point, but if you're in any doubt, see the dedicated Compatibility section for more details.
Backwards-compatible (non-breaking) changes
- Adding an API interface to an API service
- Adding a method to an API interface
- Adding an HTTP binding to a method
- Adding a field to a request message
- Adding a field to a response message
- Adding a value to an enum
- Adding an output-only resource field
Backwards-incompatible (breaking) changes
- Removing or renaming a service, interface, field, method or enum value
- Changing an HTTP binding
- Changing the type of a field
- Changing a resource name format
- Changing visible behavior of existing requests
- Changing the URL format in the HTTP definition
- Adding a read/write field to a resource message