microsoft / microsoft/api-guidelines
Re-examine guidance for including eTag in response to PUT request
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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