How document versioning works


When you first PUT a document, you can add an ‘If-None-Match:*’ header to make sure you don’t overwrite anything existing.

You will get an ETag header in the response, which you can use in the ‘If-Match’ header of any subsequent PUT requests, so that you avoid overwriting changes made from other devices.

When you GET a document, you can add an ‘If-None-Match’ header to avoid unnecessarily retrieving the version you already have. Or you can retrieve any of its parent directories to see if anything changed in them, because any change in a document will change the ETag of all of its ancestors.

Also, in a directory listing you can see the latest version of each contained item, so if you retrieve the root folder, you can see exactly where there is fresh data you don’t have yet.

When you DELETE a document, you can also do this conditionally (‘If-Match’), and this will also update the version of each ancestor folder.

Hope this explains it a bit.


I meant versioning of the spec itself. The rest is explained in the spec anyway. :smile:


Aaah ok. we update it in June and in December. The main goal is to change as little as possible each time, so we minimize bit rot. the version that is planned for publishing in June 2013 will be called remotestorage-01 and is drafted here:


So It’s just linear, and December 2013 will be -02, right?


yes, that is correct.