From 5008dba1634593cbf8f2d6eb65ad66d170d4b79d Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Sat, 23 Mar 2024 11:44:39 +0000 Subject: [PATCH 01/13] draft: AIP-4236 - API Versioning for Version-aware clients --- aip/client-libraries/4236.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 aip/client-libraries/4236.md diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md new file mode 100644 index 000000000..f461335fb --- /dev/null +++ b/aip/client-libraries/4236.md @@ -0,0 +1,36 @@ +--- +id: 4236 +state: reviewing +created: 2024-03-25 +--- + +# 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 +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 +as opaque by clients. Services may use a format with an apparent structure, +but clients must not rely on this to determine components within an API version, +or attempt to construct other valid API versions. + +### Expected Generator and Client Library Behavior + +If a service is annotated with [google.api.api_version], client library +generators **must** include the version in requests sent to the API via +the HTTP Header `X-Goog-Api-Version`. + +For HTTP Requests, an HTTP Query Parameter `$apiVersion` can be used +instead of the `X-Goog-Api-Version` HTTP header. + +Requests which contain the API version, must include either an HTTP query +parameter `X-Goog-Api-Version` or HTTP header `$apiVersion`, but not both. + +Generated documentation for a given service can include the value of +[google.api.api_version], if it exists in the source protos. + +The format of the API version must be treated as opaque by clients. Generators +and clients must not use the value of [google.api.api_version] to make decisions. + +[google.api.api_version]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto From 160884cab05fa7e0dfee7dbef79d0aff8f658b46 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Mon, 8 Apr 2024 14:54:59 +0000 Subject: [PATCH 02/13] fix copy/paste error --- aip/client-libraries/4236.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index f461335fb..83c148ad0 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -25,7 +25,7 @@ For HTTP Requests, an HTTP Query Parameter `$apiVersion` can be used instead of the `X-Goog-Api-Version` HTTP header. Requests which contain the API version, must include either an HTTP query -parameter `X-Goog-Api-Version` or HTTP header `$apiVersion`, but not both. +parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but not both. Generated documentation for a given service can include the value of [google.api.api_version], if it exists in the source protos. From 17305e5d821055ca3e39063f849fcefff8af112a Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Thu, 16 May 2024 12:47:06 -0400 Subject: [PATCH 03/13] Update AIP status --- aip/client-libraries/4236.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 83c148ad0..48f3f6ae3 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -1,7 +1,7 @@ --- id: 4236 -state: reviewing -created: 2024-03-25 +state: approved +created: 2024-05-16 --- # Version-aware clients From 82511673302ee2c3fcd19cfefc0231b7daa226c2 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 13:59:29 +0000 Subject: [PATCH 04/13] address review feedback --- aip/client-libraries/4236.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 48f3f6ae3..a0bc9cdf8 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -1,23 +1,23 @@ --- id: 4236 -state: approved +state: reviewing created: 2024-05-16 --- # 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 -the value of [google.api.api_version] in the request to the API. This allows +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. 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 +this API version was deployed. The format of the API version **must** be treated as opaque by clients. Services may use a format with an apparent structure, -but clients must not rely on this to determine components within an API version, +but clients **must not** rely on this to determine components within an API version, or attempt to construct other valid API versions. ### Expected Generator and Client Library Behavior -If a service is annotated with [google.api.api_version], client library +If a service is annotated with `google.api.api_version`, client library generators **must** include the version in requests sent to the API via the HTTP Header `X-Goog-Api-Version`. @@ -25,12 +25,16 @@ For HTTP Requests, an HTTP Query Parameter `$apiVersion` can be used instead of the `X-Goog-Api-Version` HTTP header. Requests which contain the API version, must include either an HTTP query -parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but not both. +parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but a request +**must not** contain both. -Generated documentation for a given service can include the value of -[google.api.api_version], if it exists in the source protos. +Generated documentation for a given service **may** include the value of +`google.api.api_version`, if it exists in the source protos. -The format of the API version must be treated as opaque by clients. Generators -and clients must not use the value of [google.api.api_version] to make decisions. +## Rationale -[google.api.api_version]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto +The format of the API version **must** be treated as opaque by clients. Generators and +clients **must not** interpret the value of `google.api.api_version` beyond the uses +mentioned above. + +[`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto From 60a868c0a6ffeed7c1a0bc56575eec7a3d46a767 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 14:01:54 +0000 Subject: [PATCH 05/13] address review feedback --- aip/client-libraries/4236.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index a0bc9cdf8..5c1f6735e 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -11,8 +11,7 @@ APIs can annotate services with [`google.api.api_version`][]. If 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 -as opaque by clients. Services may use a format with an apparent structure, -but clients **must not** rely on this to determine components within an API version, +as opaque by clients. Clients **must not** rely on this to determine components within an API version, or attempt to construct other valid API versions. ### Expected Generator and Client Library Behavior @@ -21,10 +20,10 @@ If a service is annotated with `google.api.api_version`, client library generators **must** include the version in requests sent to the API via the HTTP Header `X-Goog-Api-Version`. -For HTTP Requests, an HTTP Query Parameter `$apiVersion` can be used +For HTTP Requests, an HTTP Query Parameter `$apiVersion` **may** be used instead of the `X-Goog-Api-Version` HTTP header. -Requests which contain the API version, must include either an HTTP query +Requests which contain the API version, **must** include either an HTTP query parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but a request **must not** contain both. From 48e63e417932d15f8475b54d8f8bd5f1ec10add1 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 14:04:59 +0000 Subject: [PATCH 06/13] address review feedback --- aip/client-libraries/4236.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 5c1f6735e..eee44d30a 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -6,13 +6,9 @@ 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. 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 -as opaque by clients. Clients **must not** rely on this to determine components within an API version, -or attempt to construct other valid API versions. +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 @@ -32,8 +28,9 @@ Generated documentation for a given service **may** include the value of ## Rationale -The format of the API version **must** be treated as opaque by clients. Generators and -clients **must not** interpret the value of `google.api.api_version` beyond the uses -mentioned above. +The `google.api.api_version` annotation allows services to abide by the schema and +behavior of the service at the time that the API version was deployed. The format of the +API version **must** be treated as opaque by clients. Generators and clients **must not** +interpret the value of `google.api.api_version` beyond the uses mentioned above. [`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto From 9a8ebeef5e917c0a77444c82e72b415bbea559d2 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 14:05:51 +0000 Subject: [PATCH 07/13] address review feedback --- aip/client-libraries/4236.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index eee44d30a..d108167c0 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -16,9 +16,6 @@ If a service is annotated with `google.api.api_version`, client library generators **must** include the version in requests sent to the API via the HTTP Header `X-Goog-Api-Version`. -For HTTP Requests, an HTTP Query Parameter `$apiVersion` **may** be used -instead of the `X-Goog-Api-Version` HTTP header. - Requests which contain the API version, **must** include either an HTTP query parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but a request **must not** contain both. From 67e664a692b57e01b03121c4df97ae83a949ae3b Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 14:06:39 +0000 Subject: [PATCH 08/13] grammar --- aip/client-libraries/4236.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index d108167c0..9ed813d5d 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -26,7 +26,7 @@ Generated documentation for a given service **may** include the value of ## Rationale The `google.api.api_version` annotation allows services to abide by the schema and -behavior of the service at the time that the API version was deployed. The format of the +service behavior at the time that the API version was deployed. The format of the API version **must** be treated as opaque by clients. Generators and clients **must not** interpret the value of `google.api.api_version` beyond the uses mentioned above. From f46c82ea6e80acb6d86da52635bd184d8dc61849 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 14:07:00 +0000 Subject: [PATCH 09/13] grammar --- aip/client-libraries/4236.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 9ed813d5d..135c5940f 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -26,7 +26,7 @@ Generated documentation for a given service **may** include the value of ## Rationale The `google.api.api_version` annotation allows services to abide by the schema and -service behavior at the time that the API version was deployed. The format of the +service behavior at the time the API version was deployed. The format of the API version **must** be treated as opaque by clients. Generators and clients **must not** interpret the value of `google.api.api_version` beyond the uses mentioned above. From 3db46982f809e0d52f144cd8e19a5a7f16fc0fe3 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Tue, 21 May 2024 15:07:11 +0000 Subject: [PATCH 10/13] address review feedback --- aip/client-libraries/4236.md | 37 ++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 135c5940f..e06e51dee 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -13,21 +13,38 @@ 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 the version in requests sent to the API via -the HTTP Header `X-Goog-Api-Version`. - -Requests which contain the API version, **must** include either an HTTP query -parameter `$apiVersion` or HTTP header `X-Goog-Api-Version`, but a request -**must not** contain both. +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. ## Rationale -The `google.api.api_version` annotation allows services to abide by the schema and -service behavior at the time the API version was deployed. The format of the -API version **must** be treated as opaque by clients. Generators and clients **must not** -interpret the value of `google.api.api_version` beyond the uses mentioned above. +### 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 + +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. + +### 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 From a228cba6a2a5a923473d284078e1a6986d144ca5 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Wed, 22 May 2024 10:55:46 +0000 Subject: [PATCH 11/13] address review feedback --- aip/client-libraries/4236.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index e06e51dee..4aa3d4458 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -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 +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. + ## Rationale ### Necessity for Versioning @@ -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 From 15e5eae508706fd6d63990a8838d51f2329c142a Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Wed, 22 May 2024 12:25:00 -0400 Subject: [PATCH 12/13] Update aip/client-libraries/4236.md Co-authored-by: Noah Dietz --- aip/client-libraries/4236.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 4aa3d4458..5083d95b7 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -19,7 +19,7 @@ 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 +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. From e7c97cb0b63bee08c0ac198b581215875527740f Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Wed, 22 May 2024 12:25:06 -0400 Subject: [PATCH 13/13] Update aip/client-libraries/4236.md Co-authored-by: Noah Dietz --- aip/client-libraries/4236.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/client-libraries/4236.md b/aip/client-libraries/4236.md index 5083d95b7..de144965a 100644 --- a/aip/client-libraries/4236.md +++ b/aip/client-libraries/4236.md @@ -21,7 +21,7 @@ Generated documentation for a given service **may** include the value of 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 +version string **must not** be parsed or interpreted for any purpose beyond identifying the intended API version. ## Rationale