This AIP is currently under review. This means that the editors have read it and are in high-level concurrence, and while it is not yet fully approved, we have a good faith expectation that the AIP will be approved in something close to its current state.

AIP-4236

Version-aware clients

APIs can annotate services 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.

Expected Generator and Client Library Behavior

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

Generated documentation for a given service may include the value of google.api.api_version, if it exists in the source protos.

Clients 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 service. This allows the service to respond in a manner consistent with the client's understanding, 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 relying on this opaque identifier, clients avoid making assumptions about the underlying versioning scheme, which may change independently of the API itself. This flexibility allows 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.