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