Skip to content

Commit c6983c7

Browse files
committed
Add additional guidance for ETag computation
1 parent 3c7416c commit c6983c7

File tree

1 file changed

+8
-0
lines changed

1 file changed

+8
-0
lines changed

azure/Guidelines.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -988,12 +988,20 @@ When supporting optimistic concurrency:
988988
#### Computing ETags
989989
The strategy that you use to compute the `ETag` depends on its semantic. For example, it is natural, for resources that are inherently versioned, to use the version as the value of the `ETag`. Another common strategy for determining the value of an `ETag` is to use a hash of the resource. If a resource is not versioned, and unless computing a hash is prohibitively expensive, this is the preferred mechanism.
990990

991+
:ballot_box_with_check: **YOU SHOULD** use a hash of the representation of a resource rather than a last modified/version number
992+
993+
> While it may be tempting to use a revision/version number for the resource as the ETag, it interferes with client's ability to retry update requests. If a client sends a conditional update request, the service acts on the request, but the client never receives a response, a subsequent identical update will be seen as a conflict even though the retried request is attempting to make the same update.
994+
991995
:ballot_box_with_check: **YOU SHOULD**, if using a hash strategy, hash the entire resource.
992996

997+
:ballot_box_with_check: **YOU SHOULD**, if supporting range requests, use a strong ETag in order to support caching.
998+
993999
:heavy_check_mark: **YOU MAY** use or, include, a timestamp in your resource schema. If you do this, the timestamp shouldn't be returned with more than subsecond precision, and it SHOULD be consistent with the data and format returned, e.g. consistent on milliseconds.
9941000

9951001
:heavy_check_mark: **YOU MAY** consider Weak ETags if you have a valid scenario for distinguishing between meaningful and cosmetic changes or if it is too expensive to compute a hash.
9961002

1003+
:white_check_box: **DO**, when supporting multiple representations (e.g. Content-Encodings) for the same resource, generate different ETag values for the different representations.
1004+
9971005
### Distributed Tracing & Telemetry
9981006
Azure SDK client guidelines specify that client libraries must send telemetry data through the `User-Agent` header, `X-MS-UserAgent` header, and Open Telemetry.
9991007
Client libraries are required to send telemetry and distributed tracing information on every request. Telemetry information is vital to the effective operation of your service and should be a consideration from the outset of design and implementation efforts.

0 commit comments

Comments
 (0)