Skip to content

FIX(AIP-157): clarify distinction between request and request message #1174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
metamatt wants to merge 2 commits into
base: master
Choose a base branch
from
Open

FIX(AIP-157): clarify distinction between request and request message #1174

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5400a26
FIX(AIP-157): clarify distinction between request message and side ch…
metamatt Jul 17, 2023
1660cb2
Merge branch 'master' into master
toumorokoshi Jul 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions aip/general/0157.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
[AIP-126]: ./0126.md