AIP-184

API version identifiers

Interface-based API versioning 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.

Changelog

  • 2026-08-17: Initial AIP-184 release.