AIP-157

Partial responses

Sometimes, a resource can be either large or expensive to compute, and the API needs to give the user control over which fields it sends back.

Guidance

APIs may support partial responses. When partial responses are needed, APIs should use view enumerations as the primary pattern. Alternatively, an API may support partial responses via infrastructure-level field mask parameters.

View enumeration

APIs should support partial responses with view enums. View enums are useful for situations where an API wants to expose a small number of predictable permutations to the user:

enum BookView {
  // The default / unset value.
  // The API will default to the BASIC view.
  BOOK_VIEW_UNSPECIFIED = 0;

  // Include basic metadata about the book, but not the full contents.
  // This is the default value (for both ListBooks and GetBook).
  BOOK_VIEW_BASIC = 1;

  // Include everything.
  BOOK_VIEW_FULL = 2;
}
  • The enum should be specified as a view field on the request message.
  • The enum should be named something ending in -View
  • The enum should at minimum have values named BASIC and FULL (although it may have values other than these).
  • The UNSPECIFIED value must be valid (not an error), and the API must document what the unspecified value will do.
    • For List RPCs, the effective default value should be BASIC.
    • For the following RPC types, the effective default value should be either BASIC or FULL:
      • Get
      • Create
      • Update
      • Soft Delete
      • Custom Method
  • The enum should be defined at the top level of the proto file (as it is likely to be needed in multiple requests, e.g. both Get and List). See AIP-126 for more guidance on top-level enumerations.

  • APIs may add fields to a given view over time. APIs must not remove a field from a given view (this is a breaking change).

    Note: If a service requires (or might require) multiple views with overlapping but distinct values, there is a potential for a namespace conflict. In this situation, the service should nest the view enum within the individual resource.

    Note: Having a partial response be the default of standard methods can degrade the effectiveness of declarative clients. Providing a mechanism to request the full resource be populated in the response, like this View pattern, is preferred if partial responses are deemed necessary.

Field masks parameter

Alternatively, an API may support partial responses using field masks (google.protobuf.FieldMask) 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 parameter, an HTTP header, or a gRPC metadata entry. Google Cloud APIs specify field masks as a system parameter.

Field masks should not be specified in the request.

  • The value of the field mask parameter must be a google.protobuf.FieldMask.
  • The field mask parameter must be optional:
    • If the field mask parameter is omitted, it must return all fields (or the default view documented for the method).
    • API infrastructure or intermediary proxies may support wildcard values such as * to indicate all fields. However, standard Protocol Buffer runtime libraries do not recognize * as a valid field path.
    • Services implementing partial response filtering should be aware that intermediary infrastructure may normalize, transform, or omit mask paths before they reach the service. An empty field mask should generally be treated as requesting all fields (or the default view).
  • APIs are discouraged from supporting non-terminal repeated fields (e.g. authors.*.given_name) in read masks, as standard Protocol Buffer runtime libraries do not support traversing beyond repeated fields (see AIP-161).

Note: Changing the default value of the field mask parameter is a breaking change.

Read masks as a request field

Warning: Read mask as a single, explicit field on the request message is DEPRECATED for Google APIs. The system parameter must be used instead. The following guidance is for the benefit of existing legacy Google and external 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:
    • If the field mask is not provided, all fields must be returned.
  • Standard Protocol Buffer runtime libraries do not support wildcards (*) or non-terminal repeated fields in field masks.

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

  • 2026-10-08: Elevate View enumeration to the primary recommendation for partial responses; clarify standard Protocol Buffer library behavior for field masks.
  • 2025-10-03: Added default view guidance for other RPC types, and declarative client warning.
  • 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.
  • 2021-03-04: Added guidance for conflicting view enums.