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