Update
In REST APIs, it is customary to make a PATCH
or PUT
request to a
resource’s URI (for example, /v1/publishers/{publisher}/books/{book}
) in
order to update that resource.
Resource-oriented design (AEP-121) honors this pattern through the Update
method (which mirrors the REST PATCH
behavior). These methods accept the URI
representing that resource and return the resource.
Guidance
APIs should provide an update method for resources unless it is not valuable for users to do so. The purpose of the update method is to make changes to the resources without causing side effects.
Update methods are specified using the following pattern:
- The method’s name must begin with the word
Update
. The remainder of the method name must be the singular form of the resource’s name. - The request schema’s name must exactly match the RPC name, with a
Request
suffix. - The response schema must be the resource itself.
- The response should include the fully-populated resource, and must include any fields that were sent and included in the update mask unless they are input only (see AEP-203).
- If the update RPC is long-running, the response
must be an
Operation
for which the return type is the resource itself.
- The method should support partial resource update, and the HTTP verb
should be
PATCH
.
-
The request’s
path
field must map to the URI path.- The
path
field must be the only variable in the URI path.
- The
-
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"{resource},update_mask"
.
Note: OAS example not yet written.
Request schema
Update methods implement a common request pattern:
- The request must contain a field for the resource.
- The name of this field must be the singular form of the resource’s name.
- The request must not contain any required fields other than those described in this section, and should not contain other optional fields except those described in this or another AEP.
- A
path
field must be included.- The field must be annotated as required.
- The field must identify the resource type that it references.
- The request message field for the resource must map to the
PATCH
body. - The request message field for the resource should be annotated as
required.
- The field must identify the resource type of the resource being updated.
- If partial resource update is supported, a field mask must be included.
It must be of type
google.protobuf.FieldMask
, and it must be calledupdate_mask
.-
The fields used in the field mask correspond to the resource being updated (not the request message).
-
The field may be required or optional. If it is required, it must include the corresponding annotation. If optional, the service must treat an omitted field mask as an implied field mask equivalent to all fields that are populated (have a non-empty value).
-
Update masks must support a special value
*
, meaning full replacement (the equivalent ofPUT
).
-
Note: OAS example not yet written.
Side effects
In general, update methods are intended to update the data within the resource. Update methods should not trigger other side effects. Instead, side effects should be triggered by custom methods.
In particular, this entails that state fields must not be directly writable in update methods.
PATCH and PUT
We standardize on PATCH
because many organizations update stable APIs in
place with backwards-compatible improvements. It is often necessary to add a
new field to an existing resource, but this becomes a breaking change when
using PUT
.
To illustrate this, consider a PUT
request to a Book
resource:
Next consider that the resource is later augmented with a new field (here we
add rating
, and use a protobuf example without loss of generality):
If a rating were set on a book and the existing PUT
request were executed, it
would wipe out the book’s rating. In essence, a PUT
request unintentionally
would wipe out data because the previous version did not know about it.
Long-running update
Some resources take longer to update a resource than is reasonable for a regular API request. In this situation, the API should use a long-running operation instead:
- The response type must be set to the resource (what the return type would be if the method were not long-running).
-
Both the
response_type
andmetadata_type
fields must be specified.
Note: OAS example not yet written.
Create or update
If the service uses client-assigned resource paths, Update
methods may
expose a bool allow_missing
field, which will cause the method to succeed in
the event that the user attempts to update a resource that is not present (and
will create the resource in the process):
Note: OAS example not yet written.
More specifically, the allow_missing
flag triggers the following behavior:
- If the method call is on a resource that does not exist, the resource is
created. All fields are applied regardless of any provided field mask.
- However, if any required fields are missing or fields have invalid values,
an
INVALID_ARGUMENT
error is returned.
- However, if any required fields are missing or fields have invalid values,
an
- If the method call is on a resource that already exists, and all fields match, the existing resource is returned unchanged.
- If the method call is on a resource that already exists, only fields declared in the field mask are updated.
The user must have the update permissions to call Update
even with
allow_missing
set to true
.
Etags
An API may sometimes need to allow users to send update requests which are
guaranteed to be made against the most current data (a common use case for this
is to detect and avoid race conditions). Resources which need to enable this do
so by including a string etag
field, which contains an opaque,
server-computed value representing the content of the resource.
In this situation, the resource should contain a string etag
field:
Note: OAS example not yet written.
The etag
field may be either required or optional. If it is set,
then the request must succeed if and only if the provided etag matches the
server-computed value, and must fail with an ABORTED
error otherwise. The
update_mask
field in the request does not affect the behavior of the etag
field, as it is not a field being updated.
Expensive fields
APIs sometimes encounter situations where some fields on a resource are expensive or impossible to reliably return.
This can happen in a few situations:
- A resource may have some fields that are very expensive to compute, and that are generally not useful to the customer on update requests.
- A single resource sometimes represents an amalgamation of data from multiple underlying (and eventually consistent) data sources. In these situations, it may be infeasible to return authoritative information on the fields that were not changed.
In this situation, an API may return back only the fields that were updated and omit the rest. APIs that do this must document this behavior.
Errors
See errors, in particular when to use PERMISSION_DENIED and NOT_FOUND errors.
In addition, if the user does have proper permission, but the requested
resource does not exist, the service must error with NOT_FOUND
(HTTP 404)
unless allow_missing
is set to true
.