Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 16 commits into from
May 22, 2024
Merged

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

Changes from 2 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
5008dba
draft: AIP-4236 - API Versioning for Version-aware clients
parthea Mar 23, 2024
160884c
fix copy/paste error
parthea Apr 8, 2024
ff7f9bc
Merge branch 'master' into api-versioning-draft
parthea Apr 8, 2024
17305e5
Update AIP status
parthea May 16, 2024
1910500
Merge branch 'master' into api-versioning-draft
parthea May 16, 2024
8251167
address review feedback
parthea May 21, 2024
60a868c
address review feedback
parthea May 21, 2024
48e63e4
address review feedback
parthea May 21, 2024
9a8ebee
address review feedback
parthea May 21, 2024
67e664a
grammar
parthea May 21, 2024
f46c82e
grammar
parthea May 21, 2024
3db4698
address review feedback
parthea May 21, 2024
a228cba
address review feedback
parthea May 22, 2024
2e79b89
Merge branch 'master' into api-versioning-draft
parthea May 22, 2024
15e5eae
Update aip/client-libraries/4236.md
parthea May 22, 2024
e7c97cb
Update aip/client-libraries/4236.md
parthea May 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions aip/client-libraries/4236.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@ 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
parthea marked this conversation as resolved.
Show resolved Hide resolved
robust compatibility. This means that the specific format or structure of the
version string should not be parsed or interpreted for any purpose beyond identifying
parthea marked this conversation as resolved.
Show resolved Hide resolved
the intended API version.

Copy link

@zhumin8 zhumin8 May 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Let's state something along the lines of:

Suggested change
Generated client library should not let users override the `X-Goog-Api-Version` HTTP header. This should be regardless if the service is annotated with [google.api.api_version].

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's only so much you can do to protect users who are determined to do weird things.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Expand All @@ -32,13 +37,11 @@ or unexpected results due to incompatible changes.

### Importance of Opaque Treatment

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
should not be parsed or interpreted for any purpose beyond identifying the intended API
version. 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 service providers to evolve their versioning
strategies without impacting client compatibility.

### Mutual Exclusivity of Query and Header

Expand Down
Loading