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 List/Get RPC requests. - The enum should be named something ending in
-View
- The enum should at minimum have values named
BASIC
andFULL
(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
orFULL
.
- For List RPCs, the effective default value should be
- The enum should be defined at the top level of the proto file (as it is needed in both the Get and List request).
- 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).
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 namedread_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.
- An explicit value of
- 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.