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 in one of the three ways:

Field masks parameter

Field masks (google.protobuf.FieldMask) can be used for granting the user fine-grained control over what fields are returned. It is generally the recommended way for an API to support partial responses.

To enable field masks, an API should support the masks as a system parameter. This parameter can be specified either using an HTTP query parameter or an HTTP header (or a gRPC metadata entry).

• The value of the field mask parameter must be a google.protobuf.FieldMask.
• The field mask parameter should be specified using $field as a query parameter or X-Goog-FieldMask as an HTTP header.
• The field mask parameter must 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.

View enumeration

Alternatively, an API may support partial responses with view enums. View enums are useful for situations where an API only wants to expose a small number of 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).
  BASIC = 1;

  // Include everything.
  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 Get RPCs, the effective default value should be either BASIC or FULL.
• 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).

• 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.

Read masks as a request field

Similar to a system parameter, 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.

Changelog

• 2021-10-06: Updated the guidance with system parameters.
• 2021-03-04: Added guidance for conflicting view enums.