Versioning

Since one API service may provide multiple API interfaces, the API versioning strategy applies at the 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 version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner,
3. PATCH version 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 as the last component of the proto package name, for example google.pubsub.v1. The major version may be omitted from the proto package name in the rare case that the package contains obviously stable types and interfaces that don't expect to have breaking changes, for example google.protobuf and google.longrunning.
• For all versions of the API other than v1, the major version number must be encoded as the last component of the proto package name. For example, google.pubsub.v2.

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:

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.

Backwards compatibility

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 design compatibility page 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 proto field number
• 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