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 (but the same API must not use both):

View enumeration

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

Read masks are useful for granting the user fine-grained control over what fields are returned, and are specified as a single field on the request message: google.protobuf.FieldMask read_mask.

  • The field mask must be a google.protobuf.FieldMask and should be named read_mask.
  • The field mask should be optional, and the API should provide and document an appropriate default if the field mask is not provided.
    • An explicit value of "*" should be supported, and must return all fields.
    • The default value may be something other than "*" (for example, if certain fields are expensive to compute and it is preferable to exclude them by default).
    • The field mask may be designated as required if necessary.
    • The default for List and Get may be different from each other. However, if they are, the default for Get must be a (non-strict) superset of the default for List.
    • While it is less common, read masks may be used on methods other than List and Get.
  • An API may allow read masks with non-terminal repeated fields (unlike update masks), but is not obligated to do so.

Choosing a strategy

Individual APIs have their own needs, and a partial response strategy that is appropriate for one API may not be appropriate for another. However, generally APIs should not be providing resource views unless they are truly needed.

Benefits of view enums

  • View enums allow an API to present the user with a limited number of choices, and are useful when presenting fine-grained control will be cumbersome, or in situations where the additional information returned represents a different tier of service.
  • View enums allow the API to add fields to each view over time, if desired.
  • View enums usually require less upkeep for users.
  • View enums are effective when the API knows which fields are expensive to compute, and that this cost will not significantly change over time.

Benefits of read masks

  • Read masks allow the user fine-grained control, and are ideal when the user wants to get precisely a certain set of fields back, and there are too many combinations to reasonably represent with view enums.
  • Read masks are beneficial when separate fields are independently expensive to compute, and an API wants to send back only the subset that the user needs.

Note: If an API requires partial responses, it should generally decide to either support view enums or read masks across the board, but not mix and match. If an API does support both, it must not support both a view and a read mask on the same resource.

Changelog

  • 2021-03-04: Added guidance for conflicting view enums.