feat(134): make etag not required

[toumorokoshi]

making etag a require field will force the user
to perform a Get of the resource first to retrieve the etag - this can cause friction for simple clients like command-line interfaces or curl-ing a resource, and makes the behavior of the standard method inconsistent across resources.

🍱 Types of changes

What types of changes does your code introduce to AEP? Put an x in the boxes
that apply

• Enhancement
• New proposal
• Migrated from google.aip.dev
• Chore / Quick Fix

📋 Your checklist for this pull request

Please review the AEP Style and Guidance for
contributing to this repository.

General

• Basic Guidance is met.
• Ensure that your PR
  references AEPs
  correctly.
• My code has been formatted
  (usually prettier -w .)

[gibson042]

This guidance relates specifically to PUT and PATCH requests, for which it can be entirely reasonable to require specification of a target ETag in every request.

[toumorokoshi]

This guidance relates specifically to PUT and PATCH requests, for which it can be entirely reasonable to require specification of a target ETag in every request.

I'm definitely open to discussing this, so thanks for posting!

Is it really reasonable to require that the user specify it on a resource-by-resource basis? What if the user doesn't really care about concurrency control for the resource?

My main concern with this requirement is that clients will then be forced to be more complex. A simple update in a shell script now requires performing a GET, then extracting the etag field from that GET to do so.

[toumorokoshi]

If you have a specific example where an etag being required (not just optional) significantly improves the usability of the resource, that would be very helpful.

[gibson042]

This is mostly moot, since e.g. If-Match: * is valid HTTP to make a request that is ostensibly conditional but in fact requires only that the target resource exists. However, it can be good to require that kind of explicit signal to avoid accidental overwrites by requests that don't include a condition at all, which is reason enough for some APIs to make it a universal requirement.

And for a concrete example, I would probably use precisely that kind of strategy for interactions that "publish" or "promote" a resource to a wider audience and/or maturity level, and also on any updates that apply to a resource required to have a linear change history (such as a document that in a more primitive or physical environment would be protected by checkout procedures). I would also expect it in e.g. an inventory system, for which lost updates can be especially problematic.

[toumorokoshi]

This guidance relates specifically to PUT and PATCH requests, for which it can be entirely reasonable to require specification of a target ETag in every request.

Sorry, I forgot to call out one detail earlier. This is referring specifically to how etags are applied to the Update (Patch) on resources. It does not modify https://aep.dev/154/, which discusses the usage of etags overall (although potentially there's some deduplication worth doing in https://aep.dev/154/#condition-headers).

And for a concrete example, I would probably use precisely that kind of strategy for interactions that "publish" or "promote" a resource to a wider audience and/or maturity level, and also on any updates that apply to a resource required to have a linear change history (such as a document that in a more primitive or physical environment would be protected by checkout procedures). I would also expect it in e.g. an inventory system, for which lost updates can be especially problematic.

I think these are good examples. My primary motivation for not requiring the field was to simplify the clients we are creating. However, I guess ultimately it's irrelevant whether the field itself is required or not because even if there's partial resource or operation support, the clients will have to eventually add functionality to interface with APIs and operations that support them anyway.

So I'll probably close this. However I will probably open a separate issue to propose removing the etag parameter as a value required on write and instead replace it with 154's behavior around ifMatch. This more closely matches the HTTP behavior (although IIRC proto-grpc mappings do not have the facility to convert something like etag to a header).

Thoughts?

[rofrankel]

What's the rationale for saying that APIs cannot make etags required for any resource?

[toumorokoshi]

There's a discussion on the overall pr here: #240 (comment).

There's some good back and forth there, but I'll close this issue since I don't think it actually achieves my goal of making full clients easier to author.

[toumorokoshi]

Closing, but please check out #241 as another opportunity to standardize behavior a bit.