Skip to content

Commit 09ca5df

Browse files
noahdietznoahdietz
committed
feat(AIP-4236): include version in client docs
1 parent 117b2b7 commit 09ca5df

1 file changed

Lines changed: 108 additions & 29 deletions

File tree

‎aip/client-libraries/4236.md‎

Lines changed: 108 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,132 @@
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+
If an API interface is annotated with `google.api.api_version`, client
18+
library generators **must** include either an HTTP query parameter `$apiVersion`
1719
or HTTP header `X-Goog-Api-Version`, but a request **must not** contain both.
1820

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

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

2791
## Rationale
2892

2993
### Necessity for Versioning
3094

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.
95+
Explicit API versioning using the `google.api.api_version` annotation is
96+
essential for maintaining compatibility between clients and services over time.
97+
As services evolve, their schemas and behaviors may change. By specifying the
98+
API version, a client communicates its expectations to the API service. This
99+
allows the API service to respond in a manner consistent with the client's
100+
understanding, preventing errors or unexpected results due to incompatible
101+
changes.
37102

38103
### Importance of Opaque Treatment
39104

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.
105+
Treating the `google.api.api_version` value as opaque is important for ensuring
106+
robust compatibility guarantees. By relying on this opaque identifier, clients
107+
avoid making assumptions about the underlying versioning scheme, which may
108+
change independently of the API itself. This flexibility allows API service
109+
providers to evolve their versioning strategies without impacting client
110+
compatibility.
45111

46112
### Mutual Exclusivity of Query and Header
47113

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

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

0 commit comments

Comments
 (0)