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

Clarify semantics of etag in delta requests/responses

    XMLWordPrintable

    Details

    • Type: New Feature
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_OS
    • Fix Version/s: V4.02
    • Component/s: Protocol
    • Labels:
      None
    • Proposal:
      Hide

      Services that support optimistic concurrency (i.e., that would return etag control information in a GET to a collection of entities) should include the current etag value in a delta response for added/updated entities (they could include for deleted entities as well, which would tell the receiver the last version of the entity when it was deleted, but it's of dubious value).

      Clients can specify an etag value in a delta update, in which case the update should only apply if the etag matches the current etag value in the server. If it does not match, then the service should either fail the entire operation, or not apply the change and mark it as a datamodificationerror in the response, depending on the continueonerror behavior.

      The special value "@odata.etag":"*" can be used to request overriding optimistic concurrency control, identical to an If-Match:* header in a PATCH request to a single entity.

      If an etag value is present, this is interpreted as an update of an existing entity, and fails if the entity doesn't exist yet.

      Without an etag value it can be interpreted as an upsert if the service doesn't require optimistic concurrency for that entity set.

      Request body example:

      {
        "@context" : "#$delta",
        "value" : [
          {
            "Id" : "New Entity",
            "Name" : "Foo",
            "BudgetCurrency" : "USD",
            "Budget" : 555.55
          },
          {
            "@odata.etag" : "W/\"197707241234132000000.0000000 \"",
            "Id" : "Existing Entity 1",
            "Name" : "Bar"
          },
          {
            "@odata.etag" : "W/\"197707240839125000000.0000000 \"",
            "@odata.removed" : {},
            "Id" : "Existing Entity 2",
          }
        ]
      }
      
      
      Show
      Services that support optimistic concurrency (i.e., that would return etag control information in a GET to a collection of entities) should include the current etag value in a delta response for added/updated entities (they could include for deleted entities as well, which would tell the receiver the last version of the entity when it was deleted, but it's of dubious value). Clients can specify an etag value in a delta update, in which case the update should only apply if the etag matches the current etag value in the server. If it does not match, then the service should either fail the entire operation, or not apply the change and mark it as a datamodificationerror in the response, depending on the continueonerror behavior. The special value "@odata.etag":"*" can be used to request overriding optimistic concurrency control, identical to an If-Match:* header in a PATCH request to a single entity. If an etag value is present, this is interpreted as an update of an existing entity, and fails if the entity doesn't exist yet. Without an etag value it can be interpreted as an upsert if the service doesn't require optimistic concurrency for that entity set. Request body example: { "@context" : "#$delta" , "value" : [ { "Id" : "New Entity" , "Name" : "Foo" , "BudgetCurrency" : "USD" , "Budget" : 555.55 }, { "@odata.etag" : "W/\" 197707241234132000000.0000000 \"", "Id" : "Existing Entity 1" , "Name" : "Bar" }, { "@odata.etag" : "W/\" 197707240839125000000.0000000 \"", "@odata.removed" : {}, "Id" : "Existing Entity 2" , } ] }

      Description

      We define that etags may be returned in a response for a single entity or as control information for each entity in a response containing a collection of entities.

      These etags can be used in an if-match header in order to enforce optimistic concurrency when updating an instance of one of these entities.

      We don't, however, describe how this applies to delta response or update payloads.

        Attachments

          Activity

            People

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

              Dates

              • Created:
                Updated:
                Resolved: