Changes overview

Major version

The major version of a service MUST be represented in its URL path, as detailed in the URI section.

Incrementing of the major version:

• MUST NOT occur unless the change results in:
  • Existing resources no longer being represented in the updated resource modeling
  • New resources using the change cannot be safely understood by existing clients
• SHOULD NOT occur more than once a year
• SHOULD NOT occur except as a part of a significant reconception of a service.

For example, a change that makes the key resource regional would require a new major version, since the new regional keys cannot be safely understood by existing clients, which expected all keys to be zonal, tied to their zone property. Instead, regional keys would need to be placed in a new /v2/keys resource scope, with a migration path to migrate zonal keys from the /v1/keys resource scope into the /v2/keys resource scope. (Depending on the broader business and technological constraints, that migration might preserve the zonal nature of the migrated key, or promote it to a regional resource.)

A new major version of a service MUST use an entirely separate resource scope^[1] that does not support resources created or managed with prior versions. Similarly, while a service MAY support multiple major versions concurrently (and MUST do so during a transition window), access to a given resource scope is by definition restricted to one major version. Custom operations MAY be provided to allow users to perform a one-way migration from a previous version, facilitating a customer to upgrade their existing resources to a new version prior to adopting that new version.

Incrementing a major version should be a tool of last resort. Before introducing a new version, carefully consider other possibilities such as introducing a new resource type, or providing tooling and guidance to allow existing clients to safely manage the transition within the existing major version.

Minor and patch versions

The minor and patch version MUST NOT be client-selectable at runtime for a service deployment.

Supported version dates

Each major version of a service MUST support a single range of contiguous API version dates.

A non-deprecated major version of a service MUST support up to (but not beyond) the current date (from 00:00 UTC of that date).

From an API client developer's perspective, any date in the supported range is equally valid. From a service developer's point of view, version dates provided by the client SHOULD be canonicalized to a small number of "inflection" dates — version dates at which the behavior of the service actually changes. This could be considered an exception to the general policy to avoid unnecessary input canonicalization.

When a client provides a version date between two inflection dates (or after the most recent inflection date), the behavior of the API MUST match the behavior defined for the closest prior inflection date. For example, if the behavior of an API mostly recently changed for the 2021-06-01 version date and a client provides 2021-06-30, that service MUST behave as if 2021-06-01 was provided.

An update to the service MAY move the oldest supported API version date forward in accordance with deprecation policies. A deprecated major version SHOULD establish a fixed last supported date when its deprecation is announced.

Version dates

An update to a service MAY support new API behavior specific to a new API version date, or across version dates, depending on the compatibility of the change. The service implementation supporting a change specific to a new API version date (e.g., 2019-11-19) MUST be released prior to that date.

Client developer directives

Client developers SHOULD be encouraged to use the current date as a version date during development and MUST be encouraged to use a fixed value for testing and production release.