Skip to content

Commit 67341b1

Browse files
noahdietznoahdietz
authored
feat(AIP-4236): include version in client docs (#1585)
1 parent 117b2b7 commit 67341b1

File tree

1 file changed

+110
-30
lines changed

1 file changed

+110
-30
lines changed

‎aip/client-libraries/4236.md‎

Lines changed: 110 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,133 @@
11
---
22
id: 4236
3-
state: reviewing
3+
state: approved
44
created: 2024-05-16
55
---
66

77
# Version-aware clients
88

9-
APIs can annotate services with [`google.api.api_version`][]. If
10-
`google.api.api_version` is specified, version-aware clients **must**
11-
include the value of `google.api.api_version` in the request to the API.
9+
APIs can annotate [API interfaces][interface def] with
10+
[`google.api.api_version`][annotation]. If `google.api.api_version` is
11+
specified, version-aware clients **must** include the value of
12+
`google.api.api_version` in the request to the API and in the documentation of
13+
the per-API interface clients.
1214

13-
### Expected Generator and Client Library Behavior
15+
## Generator and client library behavior
1416

15-
If a service is annotated with `google.api.api_version`, client library
16-
generators **must** include either an HTTP query parameter `$apiVersion`
17-
or HTTP header `X-Goog-Api-Version`, but a request **must not** contain both.
17+
If an API interface is annotated with `google.api.api_version`, client
18+
library generators **must** include either an HTTP query parameter `$apiVersion`
19+
or HTTP header/gRPC metadata key `X-Goog-Api-Version`, but a request
20+
**must not** contain both.
1821

19-
Generated documentation for a given service **may** include the value of
20-
`google.api.api_version`, if it exists in the source protos.
22+
### Generated client documentation
2123

22-
Clients **must** treat the value of `google.api.api_version` as opaque to ensure
23-
robust compatibility. This means that the specific format or structure of the
24-
version string **must not** be parsed or interpreted for any purpose beyond identifying
25-
the intended API version.
24+
Generated client documentation for a given API interface **must** include the
25+
value of `google.api.api_version`, if it exists in the source protos. The
26+
comment **must** include the original API interface name and the exact contents
27+
of the annotation.
28+
29+
**Note:** The text does not need to match exactly to the examples below, but it
30+
still needs to fulfill the requirements desribed herein.
31+
32+
For example, the following API interface definition would produce the following
33+
Go client documentation:
34+
35+
```proto
36+
service LibraryService {
37+
option (google.api.api_version) = "2026-01-01";
38+
}
39+
```
40+
41+
```go
42+
// The LibraryClient is a client for interacting with the Cloud Library...
43+
//
44+
// This client uses LibraryService version 2026-01-01.
45+
type LibraryClient struct {}
46+
```
47+
48+
Any generated documentation for an entire [API service's][service def] client
49+
package **must** include a section that lists the client-interface-version
50+
tuples present in the package. For example, the following API interface
51+
defintions would produce the following client package documentation section:
52+
53+
```proto
54+
service LibraryService {
55+
option (google.api.api_version) = "2026-01-01";
56+
}
57+
service BookService {
58+
option (google.api.api_version) = "2026-05-15";
59+
}
60+
service ShelfService {
61+
option (google.api.api_version) = "2026-02-05";
62+
}
63+
```
64+
65+
```md
66+
## API Versions
67+
68+
* LibraryClient uses LibraryService version 2026-01-01
69+
* BookClient uses BookService version 2026-05-15
70+
* ShelfClient uses ShelfService version 2026-02-05
71+
72+
```
73+
74+
If all API interfaces share the same API version, this list **should** be
75+
reduced to a single sentence for brevity. For example, if all versions were the
76+
same in the definitions above, the generated client package documentation would
77+
be as follows:
78+
79+
```md
80+
## API Versions
81+
82+
All clients use API version 2026-01-01.
83+
```
84+
85+
### Version opacity
86+
87+
Clients and generators **must** treat the value of `google.api.api_version` as
88+
opaque to ensure robust compatibility. This means that the specific format or
89+
structure of the version string **must not** be parsed or interpreted for any
90+
purpose beyond identifying the intended API version.
2691

2792
## Rationale
2893

2994
### Necessity for Versioning
3095

31-
Explicit API versioning using the `google.api.api_version` annotation is essential
32-
for maintaining compatibility between clients and services over time. As services
33-
evolve, their schemas and behaviors may change. By specifying the API version, a
34-
client communicates its expectations to the service. This allows the service to
35-
respond in a manner consistent with the client's understanding, preventing errors
36-
or unexpected results due to incompatible changes.
96+
Explicit API versioning using the `google.api.api_version` annotation is
97+
essential for maintaining compatibility between clients and services over time.
98+
As services evolve, their schemas and behaviors may change. By specifying the
99+
API version, a client communicates its expectations to the API service. This
100+
allows the API service to respond in a manner consistent with the client's
101+
intended semantics, preventing errors or unexpected results due to incompatible
102+
changes.
37103

38104
### Importance of Opaque Treatment
39105

40-
Treating the `google.api.api_version` value as opaque is important for ensuring robust
41-
compatibility guarantees. By relying on this opaque identifier, clients avoid making
42-
assumptions about the underlying versioning scheme, which may change independently of
43-
the API itself. This flexibility allows service providers to evolve their versioning
44-
strategies without impacting client compatibility.
106+
Treating the `google.api.api_version` value as opaque is important for ensuring
107+
robust compatibility guarantees. By using this identifier opaquely, clients
108+
avoid making assumptions about the underlying versioning scheme, which may
109+
change independently of the API itself. This flexibility allows API service
110+
providers to evolve their versioning strategies without impacting client
111+
compatibility.
45112

46113
### Mutual Exclusivity of Query and Header
47114

48-
Both the query parameter and header mechanisms exist to provide flexibility for different
49-
client environments. However, allowing both simultaneously could lead to ambiguity if the
50-
values differ. To ensure consistent version identification and prevent potential conflicts,
51-
only one mechanism should be used at a time.
115+
Both the query parameter and header mechanisms exist to provide flexibility for
116+
different client environments. However, allowing both simultaneously could lead
117+
to ambiguity if the values differ. To ensure consistent version identification
118+
and prevent potential conflicts, only one mechanism should be used at a time.
119+
120+
### Inclusion in documentation
121+
122+
The API version identifies the iteration of the API contract being consumed by
123+
the client and thus the end user. The end user needs a means of relating the
124+
API version in use by the client to other API artifacts (such as product
125+
documentation and other client surfaces) and vice versa.
126+
127+
[annotation]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto
128+
[interface def]: https://google.aip.dev/9#api-interface
129+
[service def]: https://google.aip.dev/9#api-service
130+
131+
## Changelog
52132

53-
[`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto
133+
- **2025-12-08**: Add documentation generation requirements and reformat.

0 commit comments

Comments
 (0)