AIP-4236 - API Versioning for Version-aware clients (#1331)

* draft: AIP-4236 - API Versioning for Version-aware clients * fix copy/paste error * Update AIP status * address review feedback * address review feedback * address review feedback * address review feedback * grammar * grammar * address review feedback * address review feedback * Update aip/client-libraries/4236.md Co-authored-by: Noah Dietz <[email protected]> * Update aip/client-libraries/4236.md Co-authored-by: Noah Dietz <[email protected]> --------- Co-authored-by: Noah Dietz <[email protected]>
aip-dev · May 22, 2024 · 50046a5 · 50046a5
1 parent 23627ed
commit 50046a5
Showing 1 changed file with 53 additions and 0 deletions.
diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md
@@ -0,0 +1,53 @@
+---
+id: 4236
+state: reviewing
+created: 2024-05-16
+---
+
+# 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.
+
+[`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto