In this article

2.2.5.4 ETag

3/6/2019

3 minutes to read

In this article

An ETag (entity tag) is an HTTP response header returned by
an HTTP/1.1 compliant web server used to determine change in content of a resource
at a given URL. The value of the header is an opaque string representing the
state of the resource at the time the response was generated.

The ETag header is used as specified in [RFC2616].
However, this document adds constraints to the header value to enable its use
for optimistic concurrency control when performing operations that update
entities on the server. Optimistic concurrency support is described in If-Match (section 2.2.5.5),
If-None-Match (section 2.2.5.6),
and later in this section.

In the Entity Data Model (EDM)
associated with a service, some EntityTypes might have properties
defined with a concurrencyMode, as specified in [MC-CSDL]
section 2.2.4,
whose value is "Fixed". Such EntityTypes are considered
enabled for optimistic concurrency control. For example, the Version
property on the Customer EntityType defined in the model shown in Appendix
A: Sample Entity Data Model and CSDL Document (section 6)
defines the entire concurrency token of the type because no other properties on
the type have the concurrencyModefacet. If a base EntityType
does not define a concurrency token, then that EntityType, and any of
its subtypes, are not considered enabled for optimistic concurrency control.

When a server responds, indicating success, to a request
performed against a URI that identifies
a single entity, properties
of an entity or a Media Resource (as specified in URI Format: Resource
Addressing Rules (section 2.2.3)), and whose EntityType
is enabled for optimistic concurrency control, it MUST include an ETag header
in the HTTP response. The value of the header MUST represent the concurrency
token for the entity that is identified by the request URI. The server MUST NOT
include an ETag header in a response to any request performed against a URI
that does not identify, as specified in URI Format: Resource Addressing
Rules (section 2.2.3), a single entity, properties of an entity, or a
Media Resource. In addition, the server MUST NOT include an ETag header if the
request URI identifies a single entity whose type is not enabled for optimistic
concurrency control. Server response requests performed against URIs that do
not return single entities MUST provide concurrency tokens in the response
payload for any entities that are enabled for concurrency control.

For example, using the model in Appendix A: Sample Entity
Data Model and CSDL Document, a valid URI identifying an EntityType
instance is http://host/service.svc/Customers('ALFKI').
As a counter example, the URIs http://host/service.svc/Customers
and http://host/service.svc/Customers('ALFKI')?$expand=Orders
identify a collection of
entities and thus MUST NOT include an ETag in a response associated with these
request URIs.

A data service MAY<52> define concurrency tokens on
the base EntityType associated with each EntitySet
in the EDM used by the service. Concurrency tokens are defined using the concurrencyMode
facet, with a value of "Fixed", on a property of an EntityType,
as specified in [MC-CSDL].

An entity's concurrency token MUST be comprised of only
primitive type values (NavigationProperties
and ComplexTypes
cannot be annotated with the concurrencyMode facet and therefore cannot
participate in the concurrency token for an EntityType), as specified in
[MC-CSDL]. Because this document relies on the definition of concurrency tokens
per [MC-CSDL], optimistic concurrency control is not defined for links
or associations.
Therefore, a server cannot perform optimistic concurrency control for
operations that create or remove associations. If a data service implementation
is able to provide concurrency support on such operations without altering the
rules in this section, it SHOULD do so.