AIP-133

Standard methods: Create

In REST APIs, it is customary to make a POST request to a collection's URI (for example, /v1/publishers/{publisher}/books) in order to create a new resource within that collection.

Resource-oriented design (AIP-121) honors this pattern through the Create method. These RPCs accept the parent collection and the resource to create (and potentially some other parameters), and return the created resource.

Guidance

APIs should generally provide a create method for resources unless it is not valuable for users to do so. The purpose of the create method is to create a new resource in an already-existing collection.

Create methods are specified using the following pattern:

rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
  option (google.api.method_signature) = "parent,book";
}

• The RPC's name must begin with the word Create. The remainder of the RPC name should be the singular form of the resource being created.
• The request message must match the RPC name, with a Request suffix.
• The response message must be the resource itself. There is no CreateBookResponse.
  • The response should include the fully-populated resource, and must include any fields that were provided unless they are input only (see AIP-203) or there is a reason to return a partial response (see AIP-157).
  • If the create RPC is long-running, the response message must be a google.longrunning.Operation which resolves to the resource itself.
• The HTTP verb must be POST.
• The collection where the resource is being added should map to the URI path.
  • The collection's parent resource should be called parent, and should be the only variable in the URI path.
  • The collection identifier (books in the above example) must be a literal string.
• There must be a body key in the google.api.http annotation, and it must map to the resource field in the request message.
  • All remaining fields should map to URI query parameters.
• There should be exactly one google.api.method_signature annotation, with a value of "parent,{resource},{resource}_id", or ""parent,{resource}" if the resource ID is not required.
• If the API is operating on the management plane, the operation should have strong consistency: the completion of a create operation must mean that all user-settable values and the existence of the resource have reached a steady-state and reading resource state returns a consistent response.

Request message

Create methods implement a common request message pattern:

message CreateBookRequest