replacing usage of update etag with AIP-154 ifMatch?

Today, there are two sightly different mechanics for validation of resource freshness. Those are:

in https://aep.dev/update, using an etag field in the resource body (proto), and rejecting the request if that does match.

In https://aep.dev/154/#guidance, using an etag header in the response, and an optional if-match header in the request for resource validation.

These are fundamentally incompatible methods, and we should provide a single way to do so. As an initial proposal, I propose aligning with AIP-154 and:

making etag a field that is returned back via grpc metadata, allowing it's usage in the HTTP header.
adding guidance in AIP-154 to use grpc metadata to include the if-match header.

one disadvantage of putting etags in the header is you won't be able to get it from the resource body (e.g. when you curl and write the output to disk for stage purpose). So it might make sense to still have an etag field in the body as place where the value is duplicated.

From https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match:

The comparison with the stored ETag uses the strong comparison algorithm, meaning two files are considered identical byte by byte only. If a listed ETag has the W/ prefix indicating a weak entity tag, this comparison algorithm will never match it.

It sounds like this means that weak etags would no longer be supported. That seems like an unfortunate limitation.

Not as important as the actual decision, but I think there some contradiction in the text of https://aep.dev/154/ which should also be resolved:

https://aep.dev/154/#guidance

Resources must support the If-Match header (and may support the If-None-Match header) if and only if resources provide the ETag.

https://aep.dev/154/#condition-headers

Services that provide ETags should support the If-Match and If-None-Match headers on incoming requests:

One is must/may for If-Match/If-None-Match and the other is should for both. Or am I reading it wrong?

Not as important as the actual decision, but I think there some contradiction in the text of https://aep.dev/154/ which should also be resolved:

https://aep.dev/154/#guidance

Resources must support the If-Match header (and may support the If-None-Match header) if and only if resources provide the ETag.

https://aep.dev/154/#condition-headers

Services that provide ETags should support the If-Match and If-None-Match headers on incoming requests:

One is must/may for If-Match/If-None-Match and the other is should for both. Or am I reading it wrong?

Good callout! In the future I'd suggest filing a separate issue so we can keep the conversation focused.

To address your point though: Yes I think those statements are not consistent, and should be. I'd probably say the latter statement is what I'd lean toward, since etags are useful in their own right for identifying whether a resource changed, even if it's not used as a check-and-set.

Offline discussion in the aep weekly today:

Concerns around the principles: should we be using gRPC metadata for all headers? consistency is good.
We should test gRPC metadata in aepc to see what the user experience is like.
A blocker would be if this breaks grpc-gateway.

maybe move aepc to envoy? not sure on grpc-gateway. Reach out to Tim burks.

@rofrankel

It sounds like this means that weak etags would no longer be supported. That seems like an unfortunate limitation.

I agree this is limiting, but I'd also note it's not explicitly stated that etag can support both strong and weak matches.

@rofrankel do you have a specific blocker if weak etags were not supported? I'll also ask around and see if someone can help clarify why weak matches aren't supported for matching, but also feel like we should validate the use case.

w.r.t. how to move forward with this ticket, I'm proposing:

we do remove the etag guidance on update - APIs can continue to provide this behavior if they wish, but we should recommend a single way to do so.
prove out the usage of HTTP headers for validation in aeps. gateway-grpc provides a way to extract custom headers, so I think this is do-able: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_your_gateway/#mapping-from-http-request-headers-to-grpc-client-metadata.

aep-dev/aepc#76 shows that grpc-gateway can indeed be modified to support if-match and etag headers. GRPC requests can also attach metadata, so I think this sufficient proves that this pattern is indeed possible to port to GRPC-based interfaces.

feat(134): replace etag guidance with 154 reference

feat(134): replace etag guidance with 154 reference (#356)

fix(137): clarify behvavior (field presence and errors).

fix(137): clarify behavior (field presence and errors). (#357)

feat(134): replace etag guidance with 154 reference (aep-dev#356)

fix(137): clarify behavior (field presence and errors). (aep-dev#357)

Navigation Menu

Repository navigation

replacing usage of update etag with AIP-154 ifMatch? #241

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

replacing usage of update etag with AIP-154 ifMatch? #241

Description

Activity

toumorokoshi commented on Nov 6, 2024

rofrankel commented on Nov 6, 2024

dv-stewarts commented on Nov 8, 2024

toumorokoshi commented on Nov 10, 2024

toumorokoshi commented on Mar 14, 2025

toumorokoshi commented on Sep 21, 2025

toumorokoshi commented on Sep 21, 2025

toumorokoshi commented on Sep 29, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions