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:

read_mask parameter

Field masks can be used for granting the user fine-grained control over what fields are returned. An API should support the mask as a request field named read_mask.

• The read_mask parameter must be optional:
  • An explicit value of "*" should be supported, and must return all fields.
  • If read_mask 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 read_mask is a breaking change.

Protocol Buffers

• The value of read_mask must be a google.protobuf.FieldMask.

  Warning: There is a known conflict between the guidance about non-terminal repeated fields guidance and the documentation of FieldMask itself: google/protobuf/field_mask.proto states that A repeated field is not allowed except at the last position of a paths string. As such, official libraries (such as Merge for FieldMasks) may not support wildcards without additional work. Track the issue here. Consider using the view enumeration pattern described below instead instead.

OpenAPI 3.0

Note: OAS example not yet written.

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:

• The enum should be specified as a view field on the request message.
• The UNSPECIFIED value must be valid (not an error), and the API must document what the unspecified value will do.
  • For List methods, the effective default value should be BASIC.
  • For Get methods, the effective default value should be either BASIC or FULL.
• 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

The implicit PATH_ONLY view described by resource association via embedded resources should not be explicitly defined in the view enum.

Protocol Buffers

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 defined within the resource; methods can reference it as e.g. Book.View.

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

OpenAPI 3.0

Note: OAS example not yet written.