Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-1293

Clarify use of etags for optimistic concurrency versus conditional fetch

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_CS01
    • Fix Version/s: V4.01_CS02
    • Component/s: None
    • Labels:
      None
    • Environment:

      [Proposed]

    • Proposal:
      Hide

      Clarify that clients are only required to specify ETags on modification operations if the resource being updated is tagged with the OptimisticConcurrency annotation.

      Each entity has its own ETag value that MUST change when structural properties or links from that entity have changed. In addition, modifying, adding, or deleting a contained entity MAY change the ETag of the parent entity.

      Collections of entities (including collections of related entities) MAY have their own ETag value whose semantics is service-specific. It typically changes if entities are added to or removed from the collection, or if an entity in the collection is changed. The ETag of a collection of related entities reached via a navigation property MAY differ from the ETag of the entity containing the navigation property.

      A Data Modification Request on an existing resource or an Action Request invoking an action bound to an existing resource MAY require optimistic concurrency control. Services SHOULD announce this via annotations with the terms Core.OptimisticConcurrency in [OData-VocCore] and Capabilities.NavigationRestrictions (nested property OptimisticConcurrencyControl) in [OData-VocCap].

      If optimistic concurrency control is required for a resource, the service MUST include an ETag header in a response to a GET request to the resource, and MAY include the ETag in a format-specific manner in responses containing that resource.

      The presence of an ETag header in a response does not imply in itself that the resource requires optimistic concurrency control; the ETag may just be used for caching and/or conditional GET requests.

      If an ETag value is specified in an If-Match or If-None-Match header of a Data Modification Request or Action Request, the operation MUST only be invoked if the If-Match or If-None-Match condition is satisfied.

      If the client does not specify an If-Match request header in a Data Modification Request or Action Request on a resource that requires optimistic concurrency control, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request. Clients can attempt to disable optimistic concurrency control by specifying

      For requests including an OData-Version header value of 4.01, any ETag values specified in the request body of an update request MUST be * or match the current value for the record being updated.

      Show
      Clarify that clients are only required to specify ETags on modification operations if the resource being updated is tagged with the OptimisticConcurrency annotation. Each entity has its own ETag value that MUST change when structural properties or links from that entity have changed. In addition, modifying, adding, or deleting a contained entity MAY change the ETag of the parent entity. Collections of entities (including collections of related entities) MAY have their own ETag value whose semantics is service-specific. It typically changes if entities are added to or removed from the collection, or if an entity in the collection is changed. The ETag of a collection of related entities reached via a navigation property MAY differ from the ETag of the entity containing the navigation property. A Data Modification Request on an existing resource or an Action Request invoking an action bound to an existing resource MAY require optimistic concurrency control. Services SHOULD announce this via annotations with the terms Core.OptimisticConcurrency in [OData-VocCore] and Capabilities.NavigationRestrictions (nested property OptimisticConcurrencyControl) in [OData-VocCap] . If optimistic concurrency control is required for a resource, the service MUST include an ETag header in a response to a GET request to the resource, and MAY include the ETag in a format-specific manner in responses containing that resource. The presence of an ETag header in a response does not imply in itself that the resource requires optimistic concurrency control; the ETag may just be used for caching and/or conditional GET requests. If an ETag value is specified in an If-Match or If-None-Match header of a Data Modification Request or Action Request , the operation MUST only be invoked if the If-Match or If-None-Match condition is satisfied. If the client does not specify an If-Match request header in a Data Modification Request or Action Request on a resource that requires optimistic concurrency control, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request. Clients can attempt to disable optimistic concurrency control by specifying For requests including an OData-Version header value of 4.01, any ETag values specified in the request body of an update request MUST be * or match the current value for the record being updated.

      Description

      Currently, it's a bit confusing whether a client has to use an etag in a data modification if supplied, or only if supplied and the item is annotated with Optimistic Concurrency.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              mikep Michael Pizzo
            • Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: