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

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

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

Warning: Read masks as a single field on the request message, for example: google.protobuf.FieldMask read_mask are DEPRECATED.

Changelog

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