Skip to content
AEP

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 to retrieve a consistent set of resources.

  • The method’s name must begin with BatchGet. The remainder of the method name must be the plural form of the resource being retrieved.
  • The HTTP verb must be GET.
  • The HTTP URI must end with :batchGet.
  • The URI path must represent the collection for the resource, matching the collection used for simple CRUD operations. If the operation spans parents, a wilcard may be accepted.
  • There must not be a request body.
    • If a GET request contains a body, the body must be ignored, and must not cause an error.

Request

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

  • The request must include an array field which accepts the resource paths specifying the resources to retrieve. The field must be named paths.
    • If no resource paths are provided, the API should error with INVALID_ARGUMENT.
    • The parameter must be required.
    • The documentation for the parameter should include the resource type that it references.
    • The parameter should define the pattern of the resource path values.
    • The parameter should define the maximum number of paths allowed.
  • 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 must not contain any other required parameters, and should not contain other optional parameters except those described in this or another AEP.
rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {
  option (google.api.http) = {
    get: "/v1/{parent=publishers/*}/books:batchGet"
  };
}


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 `paths`
  // must match this field.
  string parent = 1 [
    (google.api.resource_reference) = {
      child_type: "library.com/Book"
    }];


  // The paths of the books to retrieve.
  // A maximum of 1000 books can be retrieved in a batch.
  // Format: publishers/{publisher}/books/{book}
  repeated string paths = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.com/Book"
    }];
}

  • The request schema must match the method name, with Request suffix.

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

  • There must not be a body key in the google.api.http annotation.

Response

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

  • The response schema must match the method name, with Response suffix.
  • The response schema must have a single array property where each item is either a retrieved resource or an error structure describing an error that occurred attempting to retrieve the resource. The error alternative would only be present for non-transactional batch gets.
  • The order of resources/error objects in the response must be the same as the paths in the request.
  • The array of resources must be named results and contain resources with no additional wrapping.
  • There must not be a nextPageToken field as batch get operations are not pageable.
message BatchGetBooksResponse {
  // Books requested.
  repeated Book books = 1;
}

Support for transactional get

The batch get method may support a transactional form of operation where the get either succeeds for all requested resources or fails. When supported, the method must define a boolean parameter transactional that the user must specify with the value true to request a transactional operation.

Changelog

  • 2024-04-22: Adopt from Google AIP https://google.aip.dev/231 with the following changes:
    • Dropped the “nested requests” pattern.
    • Changed the response schema to an object with results array property.
    • Made transactional operation optional and controlled by asTransaction parameter.