Skip to content

Commit c6ff30f

Browse files
committed
Address PR review comments
1 parent b7e0d95 commit c6ff30f

File tree

2 files changed

+3
-2
lines changed

2 files changed

+3
-2
lines changed

azure/ConsiderationsForServiceDesign.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,7 @@ The following are recommended names for properties that match the associated des
148148
| lastModifiedAt | The date and time the resource was last modified. |
149149
| deletedAt | The date and time the resource was deleted. |
150150
| kind | The discriminator value for a polymorphic resource |
151+
| etag | The entity tag used for optimistic concurrency control, when included as a property of a resource. |
151152

152153
### `name` vs `id`
153154

@@ -517,7 +518,7 @@ Optimistic concurrency is a strategy used in HTTP to avoid the "lost update" pro
517518
Clients can use ETags returned by the service to specify a _precondition_ for the execution of an update, to ensure that the resource has not been updated since the client last observed it.
518519
For example, the client can specify an `If-Match` header with the last ETag value received by the client in an update request.
519520
The service processes the update only if the Etag value in the header matches the ETag of the current resource on the server.
520-
By computing and returning ETags for your resources, you enable clients to avoid using a "pessimistic" strategy where the "last write always wins."
521+
By computing and returning ETags for your resources, you enable clients to avoid using a strategy where the "last write always wins."
521522

522523
## Getting Help: The Azure REST API Stewardship Board
523524
The Azure REST API Stewardship board is a collection of dedicated architects that are passionate about helping Azure service teams build interfaces that are intuitive, maintainable, consistent, and most importantly, delight our customers. Because APIs affect nearly all downstream decisions, you are encouraged to reach out to the Stewardship board early in the development process. These architects will work with you to apply these guidelines and identify any hidden pitfalls in your design.

azure/Guidelines.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1071,7 +1071,7 @@ For more control over caching, please refer to the `cache-control` [HTTP header]
10711071
| DELETE | `If-Match` | value of ETag | value matches the latest value on the server | `204-No Content` | Response body SHOULD be empty. |
10721072
| DELETE | `If-Match` | value of ETag | value does NOT match the latest value on the server | `412-Preconditioned Failed` | Response body SHOULD be empty.|
10731073

1074-
#### ETags
1074+
#### Computing ETags
10751075

10761076
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.
10771077

0 commit comments

Comments
 (0)