AIP-233

Batch methods: Create

Some APIs need to allow users to create multiple resources in a single transaction. A batch create method provides this functionality.

Guidance

APIs may support Batch Create using the following pattern:

rpc BatchCreateBooks(BatchCreateBooksRequest) returns (BatchCreateBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchCreate"
    body: "*"
  };
}

• The RPC's name must begin with BatchCreate. The remainder of the RPC name should be the plural form of the resource being created.
• 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 :batchCreate.
• 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 should be atomic: it should 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.
  • In cases where supporting partial responses cannot be avoided, the design should follow the guidelines of AIP-193.

Request message

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

message BatchCreateBooksRequest {
  // The parent resource shared by all books being created.
  // Format: publishers/{publisher}
  // If this is set, the parent field in the CreateBookRequest 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 create.
  // A maximum of 1000 books can be created in a batch.
  repeated CreateBookRequest requests = 2
    [(google.api.field_behavior) = REQUIRED];
}

• A parent field should be included, unless the resource being created is a top-level resource. If a caller sets this field, and the parent field of any child request message does not match, the request must fail. The parent field of child request messages can be omitted if the parent field in this request is set.
  • 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 create, as specified for standard Create methods. The field should be named requests.
  • The field should be required.
• Other fields may be "hoisted" from the standard Create 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.
  • Fields which must be unique cannot be hoisted (e.g. Customer-provided id fields).
• 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 create method should be specified with the following pattern:

message BatchCreateBooksResponse {
  // Books created.
  repeated Book books = 1;
}

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

Changelog

• 2023-04-18: Changed the recommendation to allow returning partial successes.
• 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-08-01: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.