AIP-4236 - API Versioning for Version-aware clients #1331
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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. | ||||||
|
|
||||||
|
There was a problem hiding this comment. To guide consistent behavior across languages when user attempts to set a user header of the same key, this could be to override an existing version that ships with client library, or attempting to add this header when server does not opt in for this feature.
Suggested change
There was a problem hiding this comment. I'd prefer not to add that, personally. There's only so much you can do to protect users who are determined to do weird things. The chances of someone accidentally setting that header are very slim - and if someone really wants to do so, they can always send a request directly from an HTTP client. We definitely shouldn't provide any way of specifically overriding the header - but I don't think "code that allows headers to be specified" should be modified to try to prevent this. There was a problem hiding this comment.
I agree on this. On the other hand, it also seems valuable to give user usable feedback if we don't intend have this overriden. To add a bit context in Java, we already have some logic trying to resolve conflict between internal header set by defaults and user headers. I am inclined to add logic to throw exception when user attempt to add a header with key "x-goog-api-version" (draft pr). Alternative to this is no change to this existing logic, which will throw exception only when internal header has this key (that's when service has a api version). I don't feel too strongly, but the first one gives a bit more consistent feedback. I realize this is only dealing with an edge case, but also feel that this case is language agnostic, so wanted to check if we want to deal with it consistently across languages. WDTY? There was a problem hiding this comment. I think if Java wants to attempt to stop the user from doing it, that's fine - I don't think it should be in the AIP. |
||||||
| ## 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 | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've made a bunch of comments re:guidance appearing in this preamble - perhaps that means the preamble needs to be cut down/generalized/removed/converted into guidance. We don't want to repeat ourselves, we don't want to spread guidance out into various places, and we want to be succinct. Adding a
Rationalesection go/aip/8#rationale is probably where you want to be explaining the "why"There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for reviewing @noahdietz ! Please let me know if this latest version reads better.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I does! A few more tweaks thanks Tony :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please could you take another look?