From a228cba6a2a5a923473d284078e1a6986d144ca5 Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Wed, 22 May 2024 10:55:46 +0000 Subject: [PATCH] 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