aip-dev · noahdietz · Aug 17, 2026 · Aug 17, 2026
@@ -54,6 +54,11 @@ Protocol Buffers `service` definition. It is typically mapped to a similar high
 level grouping mechanism in most programming languages, like a `class` or
 `interface`.
 
+### API interface version
+
+A distinct iteration of an API interface represented by an API version
+identifier. A constituent part of an [API service version](#api-service-version).
+
 ### API method
 
 An individual operation within an API. It is typically represented in Protocol
@@ -95,6 +100,15 @@ requests. One API service may have multiple API service endpoints, such as
 Refers to the logical identifier of an API service. Google APIs use RFC 1035 DNS
 compatible names as their API service names, such as `pubsub.googleapis.com`.
 
+### API service version
+
+A distinct set of API interfaces and their contemporaneous API interface
+versions. It is scoped to an API variant. The API service version value is
+typically equal to the latest API interface version in that set. The content of
+API artifacts, such as reference documentation, client library packages, and
+other API-based tooling, are often organized around one or more service
+versions.
+
 ### API title
 
 Refers to the user-facing product title of an API service, such as "Cloud Pub/Sub
@@ -105,11 +119,30 @@ API".
 A single invocation of an API method. It is often used as the unit for billing,
 logging, monitoring, and rate limiting.
 
+### API variant
+
+The top-level iteration of an API, such as "v1beta" or "v2", that appears in API
+artifacts such as specifications, client packages, and folder-filesystem
+structure. API variants are producer-defined shorthands that demarcate
+side-by-side namespaces for API interface versions.
+
 ### API version
 
-The version of an API or a group of APIs if they are defined together. An API
-version is often represented by a string, such as "v1", and presents in API
-requests and Protocol Buffers package names.
+API version is used colloquially in reference to any of the following:
+
+- In channel-based versioning, it refers to the [API variant](#api-variant).
+- In interface-based versioning, it can refer to any of the following:
+  - [API interface version](#api-interface-version)
+  - [API service version](#api-service-version)
+  - [API version identifier](#api-version-identifier)
+
+Prefer to use the more specific term wherever possible.
+
+### API version identifier
+
+The name of a versioned iteration of an API interface, such as `2024-10-31`.
+It is the "key" to clients and services communicating via the same API. See
+[AIP-184][] for more detail on version identifiers.
 
 ### Client
 
@@ -165,9 +198,11 @@ organizations separate from those that consume them.
 
 [Declarative clients]: #declarative-clients
 [Terraform]: https://www.terraform.io/
+[AIP-184]: https://aip.dev/184
 
 ## Changelog
 
+- **2026-08-17**: Add Interface-Based Versioning glossary terms.
 - **2025-08-13**: Add API inteface entry
 - **2024-12-18**: Downcase headings and terms as per dev docs style
 - **2024-10-23**: Add API Title entry

@@ -86,3 +86,95 @@ 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.
+
+[API consumer]: https://aip.dev/9#api-consumer
+[API producer]: https://aip.dev/9#api-producer
+[AIP-185]: https://aip.dev/185
@@ -0,0 +1,133 @@
+---
+id: 184
+state: approved
+created: 2026-08-17
+placement:
+  category: compatibility
+  order: 35
+---
+
+# API version identifiers
+
+[Interface-based API versioning][AIP-185] uses version identifiers as part of the versioning
+scheme. An API version has a unique version identifier and relates an [API interface][] with a version identifier.
+
+Version identifiers can be used at a granularity level finer than identifiers
+used for channel-, release-, and visibility-based versioning described in
+[AIP-185][].
+
+## Guidance
+
+### Format
+
+Version identifiers **must** match the following format:
+
+```
+[VARIANT-]YYYY-MM-DD[-DECORATOR]
+```
+
+where:
+
+- `VARIANT`: Optional API variant component in lower camel case (for example, `v1`,
+  `v1alpha`, or `v2`). If an API has a variant, it **may** be used as a prefix
+  separated by a hyphen. It is used to disambiguate API versions with the same
+  date and decorator components across different API variants.
+- `YYYY-MM-DD`: Mandatory ISO 8601 calendar date format (for example, `2024-08-28`
+  for August 28, 2024).
+- `DECORATOR`: Optional string in lower kebab case (for example, `gke-autopilot`).
+
+The version identifier **must** have a date component that monotonically
+increases in time to represent the version sequence. A version identifier
+**must not** share a date component with another version identifier within the
+same variant.
+
+The decorator component **should** be used to indicate versions of different
+stability levels or special-purpose versions (such as private GAs).
+
+Common decorator values include:
+
+- `preview`
+- `experimental`
+
+Stable version identifiers (`YYYY-MM-DD`) **must** be used for GA APIs, with the
+exception of private GA versions that use version identifiers with a decorator
+component (for example, `YYYY-MM-DD-acme` or `YYYY-MM-DD-gke-autopilot`).
+
+Preview version identifiers (`YYYY-MM-DD-preview`) **must** only be used for
+validating pre-GA functionality by consumers.
+
+Experimental version identifiers (`YYYY-MM-DD-experimental`) **must** be used
+for highly volatile, time-bound versions.
+
+APIs **should** use common decorator values when possible and maintain local
+consistency when facing conflicting precedent.
+
+Stable (GA) API versions **must not** use a decorator. Private versions **may**
+have a decorator different from the common values to differentiate private and
+general population versions.
+
+Version identifiers **should** follow [AIP-210][] constraints for unique
+identifiers. They **should** be limited to ASCII, **must** only include letters,
+numbers, hyphens, and underscores, **should** use a maximum length of 64
+characters, and **should** always be normalized and **must** always be stored in
+normalized form to prevent collisions due to normalization.
+
+Examples:
+
+- `2025-01-01`
+- `v2-2025-01-05`
+- `2025-02-01-preview`
+- `2025-02-02-experimental`
+- `2025-03-01-gke-autopilot`
+
+From an external perspective, version identifiers are meant to be simple,
+semantically opaque strings with an equality relation:
+
+- API clients **must not** make any assumptions about the formatting or internal
+  structure of a version identifier beyond version equality.
+- APIs that have special availability, performance, and functional constraints
+  for using the standard version identifier format **may** use different version
+  identifier formats (for example, certain data plane APIs).
+
+### Semantics
+
+Version identifiers enable interacting with specific API versions.
+
+- Version identifiers **must** be provided in API requests as either header data
+  with the key `X-Goog-Api-Version` or a query parameter with the key
+  `$apiVersion` (but not both).
+
+  Examples:
+
+  ```
+  /projects/{project}/aggregated/instances?$apiVersion=2025-01-01
+  /projects/{project}/aggregated/instances?$apiVersion=2024-09-01-preview
+  ```
+
+  or
+
+  ```
+  Header: X-Goog-Api-Version: 2025-01-01
+  ```
+
+- Absent a version identifier, the API **must** fail the request with `400 Bad
+  Request`.
+- Version identifiers are immutable and **must not** be changed after the API
+  version using them is released. This means that API changes can be made to
+  specific versions without affecting other versions.
+
+  For example, a new feature can be added to version `2025-01-01` without
+  affecting version `2024-09-01`.
+
+- Version identifiers **must** be used in API documentation for documenting:
+  - The API version.
+  - The stability level of the version.
+  - The API elements available for the version.
+
+[API interface]: https://aip.dev/9#api-interface
+[AIP-185]: https://aip.dev/185
+[AIP-210]: https://aip.dev/210
+
+## Changelog
+
+- **2026-08-17**: Initial AIP-184 release.
@@ -42,6 +42,7 @@ the stability level after the major version number in the protobuf package and
 URI path using one of these strategies:
 
 - Channel-based versioning (recommended)
+- Interface-based versioning
 - Release-based versioning
 - Visibility-based versioning
 
@@ -88,6 +89,76 @@ 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.
 
+### Interface-based versioning
+
+Interface-based versioning (IBV) is a versioning system where API producers can
+iterate quickly and safely on their APIs, while API consumers can update to new
+service features on their own schedule.
+
+With IBV, consumers experience a given service's API surface through reliable
+lenses called [API versions][AIP-9], and they can pin to any supported version for
+backward compatibility. Producers provide continued support for all published
+versions of their APIs, with explicitly time-bounded previews.
+
+IBV rests on the following principles:
+
+- **Flexible versioning scope:** API versioning is scoped as small as a single
+  [API interface][AIP-9] (an individual resource or group of RPCs), or as large as an
+  entire [API service][AIP-9].
+- **Element annotations:** API elements (RPCs, fields, enum values) are
+  annotated with API version ranges indicating when they exist.
+- **Versioned requests:** API requests carry a version identifier in a header
+  or query parameter.
+- **Co-versioned resources:** Resources are co-versioned with the API
+  interfaces through which consumers access them. But producers store resource
+  definitions in a single, version-agnostic representation.
+
+#### Version designation
+
+API requests under IBV **must** send the API version identifier using either the
+`X-Goog-Api-Version` HTTP header or the `$apiVersion` URL query parameter.
+
+If no version is specified in a request, behavior depends on configuration: the
+request **may** default to a producer-chosen version (often the initial API
+version for legacy clients), **may** respect a consumer override, or **must** be
+rejected with an error if no default is available.
+
+Stable API versions **must** be a date in `YYYY-MM-DD` format, such as
+`2025-09-04`. Preview API versions **must** follow the format
+`YYYY-MM-DD-preview`, such as `2025-03-01-preview`. See [AIP-184][] for more
+details.
+
+#### Previews
+
+Preview API versions replace the need for traditional `alpha` and `beta`
+channels. Preview API versions are minted based on a given stable API version
+and represent a superset of that stable API version functionality, unless
+foreshadowing a potential incompatible change. See [AIP-181][] for more on the
+expected stability of Preview API versions.
+
+Preview API versions are explicitly time-bound in their lifecycle and **must
+not** be used for stable releases.
+
+#### API evolution
+
+Service producers **must** annotate API elements (RPCs, message fields, enum
+values) with internal annotations indicating the API version ranges in which
+these elements exist. These annotations define API screens, which represent
+version-aware lenses on the API surface.
+
+API screens determine request and response shaping in API proxies, and inform
+API documentation and API Discovery Documents. Service producers bundle API
+versions for publication, and releases of Discovery Documents, API
+documentation, and client libraries are built from these bundles.
+
+#### Deprecating API functionality
+
+Deprecations and breaking changes are gated by incorporating them in a new API
+version. Users of existing, unchanged API versions are undisturbed and can plan
+an upgrade at their own pace. Making changes to existing, non-current versions
+as well as version-gated incompatible or unsafe changes, are governed by the
+applicable deprecation policy.
+
 ### Release-based versioning
 
 **Important:** This pattern is not commonly used for new services. There are
@@ -176,8 +247,10 @@ 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.
 
+[AIP-9]: https://aip.dev/9
 [AIP-180]: https://aip.dev/180
 [AIP-181]: https://aip.dev/181
+[AIP-184]: https://aip.dev/184
 [AIP-213]: https://aip.dev/213
 [AIP-215]: https://aip.dev/215
 [api visibility]: https://github.com/googleapis/googleapis/blob/master/google/api/visibility.proto