HTTP API - Revisions and Concurrency with E-Tags

RavenDB defines some simple rules to determine how to handle concurrent or near requests from the HTTP API against the same document.

Leveraging E-Tags

Every document in RavenDB has a corresponding e-tag (entity tag). This e-tag is updated by RavenDB every time the document is changed.

When you want to update a document, you can specify the e-tag of the document you were working with in the "If-Match" element of the header. For example, using the cURL utility to build the request:

> curl --header "If-Match:dd62a2e0-2744-11df-a9ff-001c251ced36" 
         -X PUT http://localhost:8080/docs/bobs_address -d "{ FirstName : 'Bob', LastName: 'Smith', Address: '5 Elm St.' }"

If the e-tag specified in the header matches the current e-tag of the document in RavenDB, then this update will go through successfully.

If the document was updated by someone else before you, then the e-tag's won't match and RavenDB will return a conflict error:

HTTP/1.1 409 Conflict

{"url":"/docs/bobs_address","actualETag":"dd62a2e0-2744-11df-a9ff-001c251ced36","expectedETag":"ac6ca153-2745-11df-a9ff-001c251ced36",
         "error":"PUT attempted on document 'bobs_address' using a non current etag"}

At this point, the update has been rejected. Nothing on the server has changed. It's up to you to determine how to respond to this conflict.