AIP-234

Batch methods: Update

Some APIs need to allow users to modify a set of resources in a single transaction. A batch update method provides this functionality.

Guidance

APIs may support Batch Update using the following pattern:

rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchUpdate"
    body: "*"
  };
}

• The RPC's name must begin with BatchUpdate. The remainder of the RPC name should be the plural form of the resource being updated.
• The request and response messages must match the RPC name, with Request and Response suffixes.
  • However, in the event that the request may take a significant amount of time, the response message must be a google.longrunning.Operation which ultimately resolves to the Response type.
• The HTTP verb must be POST.
• The HTTP URI must end with :batchUpdate.
• 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.
• The body clause in the google.api.http annotation should be "*".
• The operation must be atomic: it must fail for all resources or succeed for all resources (no partial success).
  • If the operation covers multiple locations and at least one location is down, the operation must fail.

Request message

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

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

  // The request message specifying the resources to update.
  // A maximum of 1000 books can be modified in a batch.
  repeated UpdateBookRequest requests = 2
    [(google.api.field_behavior) = REQUIRED];
}

• A parent field should be included, unless the resource being updated is a top-level resource. If a caller sets this field, and the parent collection in the name of any resource being updated 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 update, as specified for standard Update methods. The field should be named requests.
  • The field should be required.
• Other fields may be "hoisted" from the standard Update 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.
  • The update_mask field is a good candidate for hoisting.
• 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.

Response message

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

message BatchUpdateBooksResponse {
  // Books updated.
  repeated Book books = 1;
}

• The response message must include one repeated field corresponding to the resources that were updated.

Changelog

• 2022-06-02: Changed suffix descriptions to eliminate superfluous "-".
• 2020-09-16: Suggested annotating parent and requests fields.
• 2020-08-27: Removed parent recommendations for top-level resources.
• 2019-09-11: Fixed the wording about which child field the parent field should match.
• 2019-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.