Rackspace Cloud Files: How To Use Object Versioning

We frequently update our products, and Cloud Files is no exception. In this series of technical posts, we’ll dig into how developers using the Cloud Files API can leverage new capabilities in Rackspace Cloud Files.

Object Versioning allows you to store multiple versions of your content to recover from unintended overwrites and deletions. It provides an easy method to implement version control that can be used on any type of content. It is strongly recommended that you put non-current objects in a separate container from where the current versions exist. Once you enable Object Versioning, new data written to an object causes the non-current version to be written to the separate container. Each of the non-current versions has a timestamp appended to it, so you know when it was created.

To enable Object Versioning, create a container where your non-current versions will be written. Next, set the metadata X-Versions-Location header on the container that holds the current versions of your objects. Set the metadata header to point to the new non-current version container you created. This is where your non-current versions will be stored. Once this is done, each object in your current-version container will have Object Versioning enabled; changes to the objects automatically create non-current versions in the separate container.

Nothing is written to the non-current version container when you initially PUT an object into the current-version container. Only when you make edits to the objects via PUT will you create non-current versions. These non-current versions are labeled according to the schema below.

Non-current versions are assigned the name <length><object_name>/<timestamp>, where length is the three-character zero-padded hexidecimal character length of the <object_name>, and <timestamp> is when it was initially created as a current version.

Any return status in the 2xx range, such as 202 (Accepted), notes success. Status codes in the 4xx or 5xx range note failure. You should retry your request if you receive an error. Please note, however, that if you have specified a container that does not exist as your non-current version container, a status of 412 (Precondition Failed) returns when you edit the versioned object. If you receive this error, check that the container exists.

A GET to a versioned object returns the current version of the object without having to perform any request redirects or metadata lookups.

A POST to a versioned object only updates the object’s metadata; it does not create a new version of the object. In other words, new versions are only created when the content of the object changes.

A DELETE to a versioned object removes the current version of the object and replaces it with the next-most current version, moving it from the non-current container to the current. This next-most current version carries with it any metadata last set on it. If you want to completely remove an object and you have five total versions of it, you must DELETE it five times.

Note: A large-object manifest file cannot be versioned, but it may point to versioned segments.

To turn off Object Versioning on your current version container, remove its X-Versions-Location metadata by sending an empty key value.

Example: Object Versioning with cURL

First, create a container with the X-Versions-Location header or add the header to an existing container. Also make sure the container referenced by the X-Versions-Location exists. In this example, “versions” is the name of that container; “container” is the location for the current version.

  curl -i -XPUT -H "X-Auth-Token: <token>" 
      -H "X-Versions-Location: versions" http://<storage_url>/container
  curl -i -XPUT -H "X-Auth-Token: <token>" http://<storage_url>/versions

Create an object (the first version):

  curl -i -XPUT --data-binary 1 -H "X-Auth-Token: <token>" 

See a listing of the older versions of the object:

  curl -i -H "X-Auth-Token: <token>" 

This is just one of many new features in Rackspace Cloud Files that developers can take advantage of. Cloud Files customers are urged to try out this new feature in their next API project or add it to a current application. If you’re not yet using Cloud Files, sign up for an account and check it out. And now, using Cloud Files is more affordable since we reduced the cost of Cloud Files by 33 percent.

Rack Blogger is our catchall blog byline, subbed in when a Racker author moves on, or used when we publish a guest post. You can email Rack Blogger at blog@rackspace.com.


Please enter your comment!
Please enter your name here