From 5400a2606b434ececf562505b47d9b505a9ebff2 Mon Sep 17 00:00:00 2001 From: Matt Ginzton Date: Mon, 17 Jul 2023 13:54:31 -0700 Subject: [PATCH] FIX(AIP-157): clarify distinction between request message and side channels "should not be specified in the request" is ambiguous; side channels and headers are part of the request, as is the request message. This change clarifies the AIP to refer specifically to the request message, not the entire request. Other phrasing in this AIP used "field on the request", not "field in the request", so this change is consistent with that. This change includes further trivial tweaks to whitespace and grammar that should not change the intent. --- aip/general/0157.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/aip/general/0157.md b/aip/general/0157.md index fb9066a0bc..94df946890 100644 --- a/aip/general/0157.md +++ b/aip/general/0157.md @@ -19,16 +19,15 @@ APIs **may** support partial responses in one of two ways: ### Field masks parameter Field masks (`google.protobuf.FieldMask`) can be used for granting the user -fine-grained control over what fields are returned. An API **should** support the mask in a side channel. -For example, the parameter can be specified either using an HTTP query +fine-grained control over what fields are returned. An API **should** support the mask being specified +in a side channel. For example, the parameter can be specified either using an HTTP query parameter, an HTTP header, or a [gRPC metadata entry][1]. Google Cloud APIs specify field masks as a [system parameter][0]. -Field masks **should not** be specified in the [request](./0157.md#read-masks-as-a-request-field). +Field masks **should not** be specified as a field on the [request message](./0157.md#read-masks-as-a-request-field). -- The value of the field mask parameter **must** be a `google.protobuf.FieldMask`. +- The value of the field mask parameter **must** be interpreted as a repeated `google.protobuf.FieldMask`. - The field mask parameter **must** be optional: - - An explicit value of `"*"` **should** be supported, and **must** return all - fields. + - An explicit value of `"*"` **should** be supported, and **must** return all fields. - If the field mask parameter is omitted, it **must** default to `"*"`, unless otherwise documented. - An API **may** allow read masks with non-terminal repeated fields (unlike update masks), but is not obligated to do so. @@ -89,4 +88,4 @@ enum BookView { [0]: https://cloud.google.com/apis/docs/system-parameters [1]: https://grpc.io/docs/what-is-grpc/core-concepts/#metadata -[AIP-126]: ./0126.md \ No newline at end of file +[AIP-126]: ./0126.md