2.2.5.4 ETag

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 concurrencyMode facet. 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.

Implementers of this document are recommended to order the property values that make up the concurrency token for an EntityType, and all of its subtypes, using the same order of the properties listed in the metadata document of the data service. RetrieveServiceMetadata Request (section 2.2.7.2.7) describes the Data Service Metadata document.

The syntax of the ETag header is defined as follows:

  
 ETag       = "ETag" ":" 
              entity-tag 
              CRLF                    ; exactly as specified in [RFC2616] section 14.19 
  
 entity-tag = [weak] opaque-tag       ; exactly as specified in [RFC2616] section 3.11 
  
 weak       = "W/"                    ; exactly as specified in [RFC2616] section 3.11 
  
 ; The rule below redefines the opaque-tag rule defined in [RFC2616] 
 opaque-tag = <ASCII encoded value of entityProperty rules from (section 2.2.3.1)> 
 ["," opaque-tag] 

Example following the model defined in Appendix A: Sample Entity Data Model and CSDL Document: ETag: W/"X'000000000000D2F3'"