AIP-231

Batch methods: Get

Some APIs need to allow users to get a specific set of resources at a consistent time point (e.g. using a read transaction). A batch get method provides this functionality.

Guidance

APIs may support Batch Get using the following pattern:

rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books:batchGet"
  };
}
  • The RPC's name must begin with BatchGet. The remainder of the RPC name should be the plural form of the resource being retrieved.
  • The request and response messages must match the RPC name, with Request and Response suffixes.
  • The HTTP verb must be GET.
  • The HTTP URI must end with :batchGet.
  • The URI path should represent the collection for the resource, matching the collection used for simple CRUD operations. If the operation spans parents, a dash (-) may be accepted as a wildcard.
  • There must not be a body key in the google.api.http annotation.
  • The operation must be atomic: it must fail for all resources or succeed for all resources (no partial success). For situations requiring partial failures, List (AIP-132) methods should be used.
    • If the operation covers multiple locations and at least one location is down, the operation must fail.

Request message

The request for a batch get method should be specified with the following pattern:

message BatchGetBooksRequest {
  // The parent resource shared by all books being retrieved.
  // Format: publishers/{publisher}
  // If this is set, the parent of all of the books specified in `names`
  // must match this field.
  string parent = 1 [
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The names of the books to retrieve.
  // A maximum of 1000 books can be retrieved in a batch.
  // Format: publishers/{publisher}/books/{book}
  repeated string names = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/Book"
    }];
}
  • A parent field should be included, unless the resource being retrieved is a top-level resource, to facilitate inclusion in the URI as well to permit a single permissions check. If a caller sets this field, and the parent collection in the name of any resource being retrieved does not match, the request must fail.
    • This field should be required if only 1 parent per request is allowed.
    • The field should identify the resource type that it references.
    • The comment for the field should document the resource pattern.
  • The request message must include a repeated field which accepts the resource names specifying the resources to retrieve. The field should be named names.
    • If no resource names are provided, the API should error with INVALID_ARGUMENT.
    • The field should be required.
    • The field should identify the resource type that it references.
    • The comment for the field should document the resource pattern.
  • Other fields besides name may be "hoisted" from the standard Get request. There is no way to allow for these fields to accept different values for different resources; if this is needed, use the alternative request message form.
  • Batch get should not support pagination because transactionality across API calls would be extremely difficult to implement or enforce, and the request defines the exact scope of the response anyway.
  • The request message must not contain any other required fields, and should not contain other optional fields except those described in this or another AIP.
  • The comment above the names field should document the maximum number of requests allowed.

Response message

The response for a batch get method should be specified with the following pattern:

message BatchGetBooksResponse {
  // Books requested.
  repeated Book books = 1;
}
  • The response message must include one repeated field corresponding to the resources being retrieved.
  • The order of books in the response must be the same as the names in the request.

Nested request objects

If the standard Get request message contains a field besides the resource name that needs to be different between different resources being requested, the batch message may alternatively hold a repeated field of the standard Get request message. This is generally discouraged unless your use case really requires it.

The request for a batch get method using this approach should be specified with the following pattern:

message BatchGetBooksRequest {
  // The parent resource shared by all books being retrieved.
  // Format: publishers/{publisher}
  // If this is set, the parent field in the GetBookRequest messages
  // must either be empty or match this field.
  string parent = 1 [
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The requests specifying the books to retrieve.
  // A maximum of 1000 books can be retrieved in a batch.
  repeated GetBookRequest requests = 2
    [(google.api.field_behavior) = REQUIRED];
}
  • A parent field should be included. If a caller sets this field, and the parent collection in the name of any resource being retrieved does not match, the request must fail.
    • This field should be required if only 1 parent per request is allowed.
    • The field should identify the resource type that it references.
    • The comment for the field should document the resource pattern.
  • The request message must include a repeated field which accepts the request messages specifying the resources to retrieve, as specified for standard Get methods. The field should be named requests.
    • The field should be required.
  • Other fields may be "hoisted" from the standard Get request, which means that the field can be set at either the batch level or child request level. Similar to parent, if both the batch level and child request level are set for the same field, the values must match.
  • Batch get should not support pagination because transactionality across API calls would be extremely difficult to implement or enforce, and the request defines the exact scope of the response anyway.
  • The request message must not contain any other required fields, and should not contain other optional fields except those described in this or another AIP.
  • The comment above the requests field should document the maximum number of requests allowed.

Changelog

  • 2022-06-02: Changed suffix descriptions to eliminate superfluous "-".
  • 2020-09-16: Suggested annotating parent, names, and requests fields.
  • 2020-08-27: Removed parent recommendations for top-level resources.
  • 2020-03-24: Clarified behavior if no resource names are sent.
  • 2019-09-11: Changed the primary recommendation to specify a repeated string instead of a repeated standard Get request message. Moved the original recommendation into its own section.
  • 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.