AIP-181

Stability levels

While different organizations (both inside Google and outside) have different product life cycles, AIPs refer to the stability of an API component using the following terms.

Note: These stability levels roughly correspond to the product launch stages (alpha, beta, GA) in Google Cloud, but are not identical. GCP imposes its own additional expectations and commitments on top of what is outlined here.

Alpha

An alpha component undergoes rapid iteration with a known set of users who must be tolerant of change. The number of users should be a curated, manageable set, such that it is feasible to communicate with all of them individually.

Breaking changes must be both allowed and expected in alpha components, and users must have no expectation of stability.

Beta

A beta component must be considered complete and ready to be declared stable, subject to public testing. Beta components should be exposed to an unknown and potentially large set of users. In other words, beta components should not be behind an allowlist; instead, they should be available to the public.

Because users of beta components tend to have a lower tolerance of change, beta components should be as stable as possible; however, the beta component must be permitted to change over time. These changes should be minimal but may include backwards-incompatible changes to beta components. Backwards-incompatible changes must be made only after a reasonable deprecation period to provide users with an opportunity to migrate their code. This deprecation period must be defined at the time of being marked beta.

Beta components should be time-boxed and promoted to stable if no issues are found in the specified timeframe, which should be specified at the time of being marked beta. A reasonable time period may vary, but a good rule of thumb is 90 days.

Stable

A stable component must be fully-supported over the lifetime of the major API version. Because users expect such stability from components marked stable, there must be no breaking changes to these components, subject to the caveats described below.

Major versions

When breaking changes become necessary, the API producer should create the next major version of the API, and start a deprecation clock on the existing version.

Turn-down of any version containing stable components must have a formal process defined at the time of being marked stable. This process must specify a deprecation period for users which provides them with reasonable advance warning.

Isolated changes

On very rare occasions, it could be preferable to make a small, isolated breaking change, if this will only cause inconvenience to a small subset of users. (Creating a new major version is an inconvenience to all users.) In this case, the API producer may deprecate the component, but must continue to support the component for the normal turndown period for a stable component.

Important: Making an in-place breaking change in a stable API is considered an extreme course of action, and should be treated with equal or greater gravity as creating a new major version. For example, at Google, this requires the approval of the API Governance team.

Emergency changes

In certain exceptional cases, such as security concerns or regulatory requirements, any API component may be changed in a breaking manner regardless of its stability level, and a deprecation is not promised in these situations.

Interface-based stability levels

The following concepts and stability levels pertain to the interface-based versioning pattern as described in AIP-185.

Stability axes

The points at which stability is evaluated in various user journeys include call-time compatibility and upgrade compatibility.

Call-time compatibility is typically evaluated when an API producer initiates a change to a live API version that impacts the behavior of existing traffic from existing, unchanged clients. Management and mitigation of call-time compatibility changes is the responsibility of the producer.

Upgrade compatibility is evaluated when an API consumer attempts to update the API version in use. This is evaluated continuously, from application development through to the completion of application production rollout. Management and mitigation of upgrade-time compatibility changes are the responsibility of the consumer.

Experimental

Experimental versions are offered early in the service lifecycle in order to help shape products and features prior to their preview introduction. They are typically short-lived and made available to specific consumers to evaluate specific aspects of the API under consideration for future development.

Key aspects of experimental versions regarding stability include:

• They have no call-time or upgrade compatibility guarantee whatsoever.
• They have no guaranteed lifetime, but will expire at some point.
• They are exempt from all compatibility policies.

While policy does not guarantee stability, the extremely limited and targeted nature of their use means that direct communication with consumers about changes is both possible and encouraged.

Preview

A preview version is an early iteration of a service version that is destined for GA (if all goes well). They are intended to enable early testing of a change by customers, gather customer feedback, allow customers to prepare for forthcoming features, and ensure that the GA launch will have long-term value and supportability.

Key aspects of preview versions regarding stability include:

• They have a strict time-boxed lifecycle that is communicated at inception.
• They strive to retain call-time compatibility.
• They do not provide upgrade compatibility.
• They can contain multiple, actively evaluated preview features.
• Consumers need to account for the time and effort involved in migrating off a preview version before it expires.

Given the above, preview versions are not suitable for use by consumers in production workloads.

Preview expiration

Version expiration is a multi-phased event consisting of onboarding window closure followed by final turndown and rejection of the version. The timing of these events varies, but is always stated upfront to set expectations. Communication with consumers precedes each phase.

General availability

General availability (GA) versions are stable, ready-for-production versions of a product that can be depended upon long-term, used in production workloads, and have SLAs and SLOs backed by technical support. The contents of such a version have typically progressed through the previous stability levels of experimental and preview before reaching general availability. This is especially important for non-trivial features that warrant thorough evaluation, but is not strictly a requirement for smaller, self-explanatory features.

Key aspects of general availability versions regarding stability include:

• They have a long-term support commitment.
• They have a call-time compatibility guarantee.
• They are subject to discontinuation and deprecation policies.

Regarding upgrade compatibility for general availability versions, actively supported features will adhere to upgrade compatibility requirements. However, features that are facing deprecation or substantial redesign can change in incompatible ways between two consecutive generally available versions. This will happen after the API producer has fulfilled the necessary processes for communicating the change and facilitating consumer migration as appropriate for the change.