AIP-4236

Version-aware clients

APIs can annotate API interfaces with google.api.api_version. If google.api.api_version is specified, version-aware clients must include the value of google.api.api_version in the request to the API and in the documentation of the per-API interface clients.

Generator and client library behavior

If an API interface is annotated with google.api.api_version, client library generators must include either an HTTP query parameter $apiVersion or HTTP header/gRPC metadata key X-Goog-Api-Version, but a request must not contain both.

Generated client documentation

Generated client documentation for a given API interface must include the value of google.api.api_version, if it exists in the source protos. The comment must include the original API interface name and the exact contents of the annotation.

Note: The text does not need to match exactly to the examples below, but it still needs to fulfill the requirements desribed herein.

For example, the following API interface definition would produce the following Go client documentation:

service LibraryService {
    option (google.api.api_version) = "2026-01-01";
}

// The LibraryClient is a client for interacting with the Cloud Library...
//
// This client uses LibraryService version 2026-01-01.
type LibraryClient struct {}

Any generated documentation for an entire API service's client package must include a section that lists the client-interface-version tuples present in the package. For example, the following API interface defintions would produce the following client package documentation section:

service LibraryService {
    option (google.api.api_version) = "2026-01-01";
}
service BookService {
    option (google.api.api_version) = "2026-05-15";
}
service ShelfService {
    option (google.api.api_version) = "2026-02-05";
}

## API Versions

* LibraryClient uses LibraryService version 2026-01-01
* BookClient uses BookService version 2026-05-15
* ShelfClient uses ShelfService version 2026-02-05

If all API interfaces share the same API version, this list should be reduced to a single sentence for brevity. For example, if all versions were the same in the definitions above, the generated client package documentation would be as follows:

## API Versions

All clients use API version 2026-01-01.

Version opacity

Clients and generators must treat the value of google.api.api_version as opaque to ensure robust compatibility. This means that the specific format or structure of the version string must not be parsed or interpreted for any purpose beyond identifying the intended API version.

Rationale

Necessity for Versioning

Explicit API versioning using the google.api.api_version annotation is essential for maintaining compatibility between clients and services over time. As services evolve, their schemas and behaviors may change. By specifying the API version, a client communicates its expectations to the API service. This allows the API service to respond in a manner consistent with the client's intended semantics, preventing errors or unexpected results due to incompatible changes.

Importance of Opaque Treatment

Treating the google.api.api_version value as opaque is important for ensuring robust compatibility guarantees. By using this identifier opaquely, clients avoid making assumptions about the underlying versioning scheme, which may change independently of the API itself. This flexibility allows API service providers to evolve their versioning strategies without impacting client compatibility.

Mutual Exclusivity of Query and Header

Both the query parameter and header mechanisms exist to provide flexibility for different client environments. However, allowing both simultaneously could lead to ambiguity if the values differ. To ensure consistent version identification and prevent potential conflicts, only one mechanism should be used at a time.

Inclusion in documentation

The API version identifies the iteration of the API contract being consumed by the client and thus the end user. The end user needs a means of relating the API version in use by the client to other API artifacts (such as product documentation and other client surfaces) and vice versa.

Changelog

• 2025-12-08: Add documentation generation requirements and reformat.