Skip to content
Merged
Changes from 1 commit
Commits
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
28 changes: 27 additions & 1 deletion aip/general/0157.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,10 +78,36 @@ enum BookView {

### Read masks as a request field

**Warning:** Read masks as a single field on the request message, for example: `google.protobuf.FieldMask read_mask` are **DEPRECATED**.
**Warning:** Read mask as a single, explicit field on the request message is
**DEPRECATED** for Google APIs. The [system parameter](#field-masks-parameter)
**must** be used instead. The following guidance is for the benefit of existing
Comment thread
noahdietz marked this conversation as resolved.
Google and any non-Google usage.

An API **may** support read masks as a single field on the request message:
`google.protobuf.FieldMask read_mask`.

- The read mask **must** be a `google.protobuf.FieldMask` and **should** be
named `read_mask`.
- The field mask **should** be optional:
- An explicit value of `"*"` **should** be supported, and **must** return all
fields.
- If the field mask parameter is not provided, all fields **must** be
returned.
- An API **may** allow read masks with non-terminal repeated fields (unlike
update masks), but is not obligated to do so.

## Rationale

### Deprecating `read_mask` in request messages

As mentioned, Google API infrastructure implements a service-wide response
field filtering mechanism, so there is no need for individual API methods to
specify a `read_mask` in their request schema. Doing so is both redundant and a
potential point of conflict for the client or service.

## Changelog

- **2025-06-16**: Reinstate read mask guidance as historical/external reference.
- **2023-05-09**: Fix top-level enum example and link to AIP-126.
- **2022-03-14:** Updated guidance on default value and how to specify a read mask.
- **2021-10-06:** Updated the guidance with system parameters.
Expand Down