AIP-154: Resource freshness validation (original) (raw)

AIP-154

APIs often need to validate that a client and server agree on the current state of a resource before taking some kind of action on that resource. For example, two processes updating the same resource in parallel could create a race condition, where the latter process "stomps over" the effort of the former one.

ETags provide a way to deal with this, by allowing the server to send a checksum based on the current content of a resource; when the client sends that checksum back, the server can ensure that the checksums match before acting on the request.

Guidance

A resource may include an etag field on any resource where it is important to ensure that the client has an up to date resource before acting on certain requests:

`// A representation of a book. message Book { // Other fields...

// This checksum is computed by the server based on the value of other // fields, and may be sent on update and delete requests to ensure the // client has an up-to-date value before proceeding. string etag = 99; } `

Note: ETag values should include quotes as described in RFC 7232. For example, a valid etag is "foo", not foo.

Declarative-friendly resources

A resource that is declarative-friendly (AIP-128) must include an etagfield.

Etags on request methods

In some situations, the etag needs to belong on a request message rather than the resource itself. For example, an Update standard method can "piggyback" off the etag field on the resource, but the Delete standard method can not:

`message DeleteBookRequest { // The name of the book. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "library.googleapis.com/Book" }];

// The current etag of the book. // If an etag is provided and does not match the current etag of the book, // deletion will be blocked and an ABORTED error will be returned. string etag = 2 [(google.api.field_behavior) = OPTIONAL]; } `

On a request message, the etag field should be given a behavior annotation - either REQUIRED or OPTIONAL. See AIP-203 for more information.

An etag field may also be used on custom methods, similar to the example above.

Strong and weak etags

ETags can be either "strongly validated" or "weakly validated":

Resources may use either strong or weak etags, as it sees fit, butshould document the behavior. Additionally, weak etags must have a W/prefix as mandated by RFC 7232.

Further reading

Changelog