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

parthea · 2024-03-23T11:51:28Z

The following is an AIP for the API Versioning feature in client library generators.

Googlers see b/330951736

zhumin8 · 2024-05-07T03:22:25Z

aip/client-libraries/4236.md

+
+Requests which contain the API version, must include either an HTTP query
+parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but not both.
+


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].

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'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?

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.

jskeet

I'm generally happy with this as a first pass. I suspect I may have some suggested changes over time, but that's a different matter :)

jskeet · 2024-05-07T08:32:15Z

aip/client-libraries/4236.md

+
+Requests which contain the API version, must include either an HTTP query
+parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but not both.
+


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.

parthea · 2024-05-16T16:47:57Z

@noahdietz PTAL

noahdietz

Please review all comments before responding to an individual one. Some are on the same line and impact each other.

noahdietz · 2024-05-20T22:58:42Z

aip/client-libraries/4236.md

+
+# Version-aware clients
+
+APIs may choose to annotate services with [google.api.api_version]. If 


Suggested change

APIs may choose to annotate services with [google.api.api_version]. If

APIs may choose to annotate services with [`google.api.api_version`][]. If

I think we still need the empty [] for an implicit link.

Also let's format the annotation name as code, might require updating the definition text as well.

Applies here and throughout.

noahdietz · 2024-05-20T22:59:12Z

aip/client-libraries/4236.md

+
+# Version-aware clients
+
+APIs may choose to annotate services with [google.api.api_version]. If 


Suggested change

APIs may choose to annotate services with [google.api.api_version]. If

APIs can annotate services with [google.api.api_version]. If

Don't use requirement words in non-requirement contexts

noahdietz · 2024-05-20T22:59:48Z

aip/client-libraries/4236.md

+# Version-aware clients
+
+APIs may choose to annotate services with [google.api.api_version]. If 
+[google.api.api_version] is specified, version-aware clients **must** include


Do we need to hyperlink every use of google.api.api_version?

noahdietz · 2024-05-20T23:00:18Z

aip/client-libraries/4236.md

+[google.api.api_version] is specified, version-aware clients **must** include
+the value of [google.api.api_version] in the request to the API. This allows
+services to abide by the schema and behavior of the service at the time that
+this API version was deployed. The format of the API version must be treated


Suggested change

this API version was deployed. The format of the API version must be treated

this API version was deployed. The format of the API version **must** be treated

I'm guessing this is a requirement?

aip/client-libraries/4236.md

noahdietz · 2024-05-21T14:32:43Z

aip/client-libraries/4236.md

+created: 2024-05-16
+---
+
+# Version-aware clients


I does! A few more tweaks thanks Tony :)

noahdietz

Just one more comment - I liked that opaque value requirement in the guidance, it is important stuff

noahdietz · 2024-05-21T17:22:06Z

aip/client-libraries/4236.md

+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


So these first two sentences would be really good in the guidance section e.g.

Clients **must** treat the value of `gogle.api.api_version as opaque. Specifically, the value **must not** be interpreted or parsed in any way.

Then this subsection could start:

Treating the `google.api.api_version` value as opaque is important to ensuring robust compatibility guarantees. By relying on....

Fixed in a228cba

aip/client-libraries/4236.md

Co-authored-by: Noah Dietz <[email protected]>

draft: AIP-4236 - API Versioning for Version-aware clients

5008dba

parthea mentioned this pull request Mar 23, 2024

feat: Add google.api.api_version annotation to echo.proto googleapis/gapic-showcase#1484

Merged

parthea added 2 commits April 8, 2024 14:54

fix copy/paste error

160884c

Merge branch 'master' into api-versioning-draft

ff7f9bc

parthea marked this pull request as ready for review April 8, 2024 15:58

parthea requested a review from a team as a code owner April 8, 2024 15:58

parthea assigned jskeet Apr 8, 2024

parthea requested a review from jskeet April 8, 2024 15:59

parthea mentioned this pull request Apr 8, 2024

Add support to echo back the x-goog-api-version header so that AIP-4236 can be tested googleapis/gapic-showcase#1493

Closed

zhumin8 reviewed May 7, 2024

View reviewed changes

jskeet approved these changes May 7, 2024

View reviewed changes

parthea requested review from zhumin8 and noahdietz and removed request for zhumin8 May 7, 2024 14:22

parthea assigned noahdietz and unassigned jskeet May 7, 2024

parthea added 2 commits May 16, 2024 12:47

Update AIP status

17305e5

Merge branch 'master' into api-versioning-draft

1910500

parthea changed the title ~~draft: AIP-4236 - API Versioning for Version-aware clients~~ AIP-4236 - API Versioning for Version-aware clients May 16, 2024

noahdietz requested changes May 20, 2024

View reviewed changes

address review feedback

8251167

parthea requested a review from noahdietz May 21, 2024 13:59

parthea added 5 commits May 21, 2024 14:01

address review feedback

60a868c

address review feedback

48e63e4

address review feedback

9a8ebee

grammar

67e664a

grammar

f46c82e

noahdietz reviewed May 21, 2024

View reviewed changes

address review feedback

3db4698

parthea requested a review from noahdietz May 21, 2024 16:07

noahdietz approved these changes May 21, 2024

View reviewed changes

parthea added 2 commits May 22, 2024 10:55

address review feedback

a228cba

Merge branch 'master' into api-versioning-draft

2e79b89

noahdietz reviewed May 22, 2024

View reviewed changes

aip/client-libraries/4236.md Outdated Show resolved Hide resolved

aip/client-libraries/4236.md Outdated Show resolved Hide resolved

parthea and others added 2 commits May 22, 2024 12:25

Update aip/client-libraries/4236.md

15e5eae

Co-authored-by: Noah Dietz <[email protected]>

Update aip/client-libraries/4236.md

e7c97cb

Co-authored-by: Noah Dietz <[email protected]>

parthea enabled auto-merge (squash) May 22, 2024 16:25

parthea merged commit 50046a5 into master May 22, 2024
2 checks passed

parthea deleted the api-versioning-draft branch May 22, 2024 16:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

parthea commented Mar 23, 2024 •

edited

Loading

zhumin8 May 7, 2024 •

edited

Loading

jskeet May 7, 2024

zhumin8 May 8, 2024

jskeet May 8, 2024

jskeet left a comment

jskeet May 7, 2024

parthea commented May 16, 2024

noahdietz left a comment

noahdietz May 20, 2024

noahdietz May 20, 2024

noahdietz May 20, 2024

noahdietz May 20, 2024

noahdietz May 21, 2024

noahdietz left a comment

noahdietz May 21, 2024

parthea May 22, 2024


		Requests which contain the API version, must include either an HTTP query
		parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but not both.


	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].


		# Version-aware clients

		APIs may choose to annotate services with [google.api.api_version]. If

	APIs may choose to annotate services with [google.api.api_version]. If
	APIs can annotate services with [google.api.api_version]. If

	this API version was deployed. The format of the API version must be treated
	this API version was deployed. The format of the API version must be treated

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

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

Conversation

parthea commented Mar 23, 2024 • edited Loading

zhumin8 May 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jskeet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

parthea commented May 16, 2024

noahdietz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noahdietz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

parthea commented Mar 23, 2024 •

edited

Loading

zhumin8 May 7, 2024 •

edited

Loading