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 (AEP-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 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:
- The response must be the resource itself. There is no separate response
schema.
- The response should include the fully-populated resource, and must include any fields that were provided unless they are input only (see AEP-203).
- If the create RPC is long-running, the response
message must be an
Operation
for which the type of theresponse
field is 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.
- The collection’s parent resource should be called
-
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 request message must match the RPC name, with a
-
The collection’s parent resource must 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.
- The collection identifier (
-
There must be a
body
key in thegoogle.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},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.
Note: OAS guidance not yet written
Request message
Create methods implement a common request message pattern:
- An
id
field must be included for management plane resources, and should be included for data plane resources. - The resource field must be included and must map to the POST body.
- The request message must not contain any other required fields and should not contain other optional fields except those described in this or another AEP.
- A
parent
field must be included unless the resource being created is a top-level resource. It should be calledparent
.-
The field should be annotated as
REQUIRED
. -
The field must identify the resource type of the resource being created.
-
Note: OAS guidance not yet written
Long-running create
Some resources take longer to create a resource than is reasonable for a regular API request. In this situation, the API should use a long-running operation (AEP-151) instead:
- The response type must be set to the resource (what the return type would be if the RPC was not long-running).
-
Both the
response_type
andmetadata_type
fields must be specified.
Note: OAS guidance not yet written
User-specified IDs
An API must allow a user to specify the ID component of a resource (the last segment of the resource path) on creation if the API is operating on the management plane.
On the data plane, an API should allow a user to specify the ID. Exceptional cases should have the following behavior:
- The data plane resource allows identical records without a need to disambiguate between the two (e.g. rows in a table with no primary key).
- The data plane resource will not be exposed in Declarative clients.
An API may allow the id
field to be optional, and give the resource a
system-generated ID if one is not specified.
For example:
- The
id
field must exist on the request message, not the resource itself.- The field may be required or optional. If it is required, it should include the corresponding annotation.
- The
path
field on the resource must be ignored. - The documentation should explain what the acceptable format is, and the format should follow the guidance for resource path formatting in AEP-122.
- If a user tries to create a resource with an ID that would result in a
duplicate resource path, the service must error with
ALREADY_EXISTS
.- However, if the user making the call does not have permission to see the
duplicate resource, the service must error with
PERMISSION_DENIED
instead.
- However, if the user making the call does not have permission to see the
duplicate resource, the service must error with
-
There should be exactly one
google.api.method_signature
annotation on the RPC, with a value of"parent,{resource},id"
if the resource being created is not a top-level resource, or with a value of"{resource},id"
if the resource being created is a top-level resource.
Note: OAS guidance not yet written
Errors
See errors, in particular when to use PERMISSION_DENIED and NOT_FOUND errors.
Further reading
- For ensuring idempotency in
Create
methods, see AEP-155. - For naming resources involving Unicode, see AEP-210.
Rationale
Requiring user-specified ids
Declarative clients use the resource ID as a way to identify a resource for applying updates and for conflict resolution. The lack of a user-specified ID means a client is unable to find the resource unless they store the identifier locally, and can result in re-creating the resource. This in turn has a downstream effect on all resources that reference it, forcing them to update to the ID of the newly-created resource.
Having a user-specified ID also means the client can precalculate the resource path and use it in references from other resources.