From 09ca5df220e99aeca11e96f61892cba60f5e7c4c Mon Sep 17 00:00:00 2001 From: noahdietz Date: Mon, 8 Dec 2025 10:46:27 -0800 Subject: [PATCH 1/4] feat(AIP-4236): include version in client docs --- aip/client-libraries/4236.md | 137 +++++++++++++++++++++++++++-------- 1 file changed, 108 insertions(+), 29 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index de144965a5..b84fc92ef8 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -1,53 +1,132 @@ --- id: 4236 -state: reviewing +state: approved 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. +APIs can annotate [API interfaces][interface def] with +[`google.api.api_version`][annotation]. 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. -### Expected Generator and Client Library Behavior +## 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` +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 `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. +### Generated client documentation -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. +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: + +```proto +service LibraryService { + option (google.api.api_version) = "2026-01-01"; +} +``` + +```go +// The LibraryClient is a client for interacting with the Cloud Library... +// +// This client uses LibraryService version 2026-01-01. +type LibraryClient struct {} +``` + +Generated documentation for an entire [API service's][service def] client +package **should** 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: + +```proto +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"; +} +``` + +```md +## 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: + +```md +## 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 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. +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 +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. +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 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. +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 e.g. product +documentation, other client surfaces, etc. and vice versa. + +[annotation]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto +[interface def]: https://google.aip.dev/9#api-interface +[service def]: https://google.aip.dev/9#api-service + +## Changelog -[`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto +- **2025-12-08**: Add documentation generation requirements and reformat. \ No newline at end of file From 2a60b5334164e2aeacf4e2ec96a3453b005bce66 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Tue, 9 Dec 2025 13:47:05 -0800 Subject: [PATCH 2/4] include grpc metadata in request requirement --- aip/client-libraries/4236.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index b84fc92ef8..d6f502335c 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -16,7 +16,8 @@ the per-API interface clients. 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 `X-Goog-Api-Version`, but a request **must not** contain both. +or HTTP header/gRPC metadata key `X-Goog-Api-Version`, but a request +**must not** contain both. ### Generated client documentation From d9e1a93a48feaa72061d39ba7e39713553044f38 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Tue, 9 Dec 2025 13:54:28 -0800 Subject: [PATCH 3/4] address feedback --- aip/client-libraries/4236.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index d6f502335c..f85eee1794 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -98,13 +98,13 @@ 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 -understanding, preventing errors or unexpected results due to incompatible +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 relying on this opaque identifier, clients +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 @@ -121,8 +121,8 @@ and prevent potential conflicts, only one mechanism should be used at a time. 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 e.g. product -documentation, other client surfaces, etc. and vice versa. +API version in use by the client to other API artifacts (such as product +documentation and other client surfaces) and vice versa. [annotation]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto [interface def]: https://google.aip.dev/9#api-interface From 536f23e4e9b8fe3b73fcb99678073590377823dc Mon Sep 17 00:00:00 2001 From: noahdietz Date: Tue, 9 Dec 2025 14:26:42 -0800 Subject: [PATCH 4/4] clarify pkg docs requirement --- aip/client-libraries/4236.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index f85eee1794..074290ae20 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -45,8 +45,8 @@ service LibraryService { type LibraryClient struct {} ``` -Generated documentation for an entire [API service's][service def] client -package **should** include a section that lists the client-interface-version +Any generated documentation for an entire [API service's][service def] 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: