From f7ceeaf02715c1bb859d2c4682b4b5c6407fa12c Mon Sep 17 00:00:00 2001 From: mdondorff Date: Fri, 13 May 2022 09:14:24 +0200 Subject: [PATCH 1/3] Added required order independence. This was also discussed with JJ Geewax and Angie Lin --- aip/general/0234.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/aip/general/0234.md b/aip/general/0234.md index a3a1d87bed..14d54c9f12 100644 --- a/aip/general/0234.md +++ b/aip/general/0234.md @@ -42,6 +42,8 @@ rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse) succeed for all resources (no partial success). - If the operation covers multiple locations and at least one location is down, the operation **must** fail. +- The operation **must** execute independent updates based on a point-in-time + snapshot. It it thus independent of the order of requests. ### Request message @@ -111,6 +113,7 @@ message BatchUpdateBooksResponse { ## Changelog +- **2022-05-13**: Added required order independence. - **2020-09-16**: Suggested annotating `parent` and `requests` fields. - **2020-08-27**: Removed parent recommendations for top-level resources. - **2019-09-11**: Fixed the wording about which child field the `parent` field From 00c930244fa7886eddcf2dfd33575ee8bfd4783e Mon Sep 17 00:00:00 2001 From: Noah Dietz Date: Fri, 13 May 2022 13:40:19 -0700 Subject: [PATCH 2/3] feat(AIP-4223): add guidance on client-side validation (#888) --- aip/client-libraries/4223.md | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 aip/client-libraries/4223.md diff --git a/aip/client-libraries/4223.md b/aip/client-libraries/4223.md new file mode 100644 index 0000000000..99d5c794bc --- /dev/null +++ b/aip/client-libraries/4223.md @@ -0,0 +1,44 @@ +--- +id: 4223 +state: approved +created: 2022-05-13 +--- + +# Client-side payload validation + +Client-side payload validation is the practice of inspecting the request payload +for any misconfigurations (e.g. missing required fields, attempting to update an +immutable field) prior to executing a network call with the payload. Typically, +documentation communicates the expectations of the service with regards to each +request field, including any requirements on presence or format. The +`google.api.field_behavior` annotation defined in [AIP-203][] is the +machine-readable format that services use to document behavior in relation to +specific request fields. + +## Guidance + +Client libraries **must not** implement client-side payload validation based +on the `google.api.field_behavior` annotation, except to prevent +[local failures](4223.md#local-failures). + +The reason for this is that the `google.api.field_behavior` annotation is +primarily a machine-readable form of _documentation_, and **not** a +configuration for payload validation. The annotation conveys how the service +_already_ handles the field, and alludes to a service's own payload validation +or expectations. + +Admittedly, depending on services to implement payload validation means clients +will sometimes make network calls that are bound to result in errors. Furthermore, users +then depend on services to provide actionable errors, when the client could have +provided a language-idiomatic, localized error. However, robust server-side +payload validation means that _all types_ of client (first party, third party, +`curl`, etc.) will benefit from the **same** validation, and that there is no +lag between service and clients when the field behavior changes. + +### Local failures + +Client libraries **may** implement client-side payload validation based on the +`google.api.field_behavior` annotation only to the extent that it prevents +local failures, such as crashes within the client library code itself. + +[AIP-203]: ../general/0203.md From c60e9c9e16621f49d0dd06b0494c0699dbdbb4ff Mon Sep 17 00:00:00 2001 From: Noah Dietz Date: Mon, 23 May 2022 08:00:57 -0700 Subject: [PATCH 3/3] fix typo --- aip/general/0234.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0234.md b/aip/general/0234.md index 14d54c9f12..19164f773b 100644 --- a/aip/general/0234.md +++ b/aip/general/0234.md @@ -43,7 +43,7 @@ rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse) - If the operation covers multiple locations and at least one location is down, the operation **must** fail. - The operation **must** execute independent updates based on a point-in-time - snapshot. It it thus independent of the order of requests. + snapshot. It is thus independent of the order of requests. ### Request message