microsoft / microsoft/api-guidelines

Re-examine guidance for including eTag in response to PUT request

Open
#540 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Azure Guidelines
Dominant language
No language data
Stars
23.3k
Forks
2.7k
PR merge metrics
No merged PRs in 30d

Description

Our current ConsiderationsForServiceDesign includes this statement in the PUT with additional long-running processing section:

If the resource supports ETags, the response may contain an etag header and possibly an etag property in the resource.

However, @johanste pointed out in a review comment on PR #517

Per RFC9110:

An origin server MUST NOT send a validator field (Section 8.8), such as an ETag or Last-Modified field, in a successful response to PUT unless the request's representation data was saved without any transformation applied to the content
Since the status property is readOnly, I don't see any situation where the service would be allowed to send an etag header.

If we choose to follow this aspect of the HTTP RFC, I think eTags would have to be eliminated from the vast majority of PUT responses in Azure -- not just LRO puts. Any resource with a readOnly field would be barred from returning an eTag from PUT.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the PUT with additional long-running processing section in azure/ConsiderationsForServiceDesign.md and the review comment on PR #517. Compare the current guidance with RFC9110's validator requirements, then document a decided rule for ETags in PUT responses, including whether the guidance applies beyond long-running operations.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.