object-api/v1/section_object-api-versioning.xml

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash  "&#x2013;">
<!ENTITY mdash  "&#x2014;">
<!ENTITY hellip "&#x2026;">

<!-- Useful for describing APIs -->
<!ENTITY COPY   '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
<!ENTITY GET    '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY HEAD   '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
<!ENTITY PUT    '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST   '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
]>
<section xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
    xml:id="set-object-versions">
    <title>Object versioning</title>
    <para>You can store multiple versions of your content so that you
        can recover from unintended overwrites. Object versioning is
        an easy way to implement version control, which you can use
        with any type of content.</para>
    <note>
        <para>You cannot version a large-object manifest file, but the
            large-object manifest file can point to versioned
            segments.</para>
    </note>
    <para>It is strongly recommended that you put non-current objects
        in a different container than the container where current
        object versions reside.</para>
    <procedure>
        <title>To enable and use object versioning</title>
        <step>
            <para>To enable object versioning, ask your cloud provider
                to set the <option>allow_versions</option> option to
                    <literal>TRUE</literal> in the container
                configuration file.</para>
        </step>
        <step>
            <para>Create an <literal>archive</literal> container to
                store older versions of objects.</para>
            <para>Create the <literal>archive</literal>
                container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d
Date: Thu, 23 Jan 2014 21:11:57 GMT</computeroutput></screen>
        </step>
        <step>
            <para>Create a <literal>current</literal> container to
                store current versions of objects.</para>
            <para>Include the <literal>X-Versions-Location</literal>
                header. This header defines the container that holds
                the non-current versions of your objects. You must
                UTF-8-encode and then URL-encode the container name
                before you include it in the
                    <code>X-Versions-Location</code> header. This
                header enables object versioning for all objects in
                the <literal>current</literal> container. Changes to
                objects in the <literal>current</literal> container
                automatically create non-current versions in the
                    <literal>archive</literal> container.</para>
            <para>Create the <literal>current</literal>
                container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT</computeroutput></screen>
        </step>
        <step>
            <para>Create the first version of an object in the
                    <literal>current</literal> container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
Date: Thu, 23 Jan 2014 21:31:22 GMT</computeroutput></screen>
            <para>Nothing is written to the non-current version
                container when you initially &PUT; an object in the
                    <literal>current</literal> container. However,
                subsequent &PUT; requests that edit an object trigger
                the creation of a version of that object in the
                    <literal>archive</literal> container.</para>
            <para>These non-current versions are named as
                follows:</para>
            <programlisting>&lt;length>&lt;object_name>&lt;timestamp></programlisting>
            <para>Where <literal>length</literal> is the 3-character, zero-padded
                hexadecimal character length of the object,
                <literal>&lt;object_name&gt;</literal> is the object name, and
                <literal>&lt;timestamp&gt;</literal> is the time when the object was
                initially created as a current version.</para>
        </step>
        <step>
            <para>Create a second version of the object in the
                    <literal>current</literal> container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
Date: Thu, 23 Jan 2014 21:41:32 GMT</computeroutput></screen>
        </step>
        <step>
            <para>Issue a &GET; request to a versioned object to get
                the current version of the object. You do not have to
                do any request redirects or metadata lookups.</para>
            <para>List older versions of the object in the
                    <literal>archive</literal> container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 30
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
Date: Thu, 23 Jan 2014 21:45:50 GMT

009my_object/1390512682.92052</computeroutput></screen>
            <note>
                <para>A &POST; request to a versioned object updates
                    only the metadata for the object and does not
                    create a new version of the object. New versions
                    are created only when the content of the object
                    changes.</para>
            </note>
        </step>
        <step>
            <para>Issue a &DELETE; request to a versioned object to
                remove the current version of the object and replace
                it with the next-most current version in the
                non-current container.</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT</computeroutput></screen>
            <para>List objects in the <literal>archive</literal>
                container to show that the archived object was moved
                back to the <literal>current</literal>
                container:</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
            <screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 0
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
Date: Thu, 23 Jan 2014 21:51:41 GMT</computeroutput></screen>
            <para>This next-most current version carries with it any
                metadata last set on it. If want to completely remove
                an object and you have five versions of it, you must
                &DELETE; it five times.</para>
        </step>
        <step>
            <para>To disable object versioning for the
                    <literal>current</literal> container, remove its
                    <literal>X-Versions-Location</literal> metadata
                header by sending an empty key value.</para>
            <screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: "</userinput></screen>
            <screen><computeroutput>HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe2476de217134549996d0-0052e19038
Date: Thu, 23 Jan 2014 21:57:12 GMT

&lt;html>&lt;h1>Accepted&lt;/h1>&lt;p>The request is accepted for processing.&lt;/p>&lt;/html></computeroutput></screen>
        </step>
    </procedure>
</section>