openstack-attic/object-api
Code Issues Proposed changes

Merge "Update Object Storage API Reference"

Browse Source
This commit is contained in:
Jenkins 2014-02-16 22:06:20 +00:00 committed by Gerrit Code Review
commit ceaced1d14
43 changed files with 2963 additions and 3271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
.gitignore vendored
View File

@ -1,17 +1,24 @@
.DS_Store? .DS_Store
*.xpr
.idea
# Build results # Build results
target/ target/
publish-docs/ publish-docs/
/build-*.log.gz /build-*.log.gz
# NetBeans user-specific build actions # Ignore Vagrant Related Files
nbactions.xml acceptance_config.yml
boxes/*
/.vagrant
# Testenvironment # Testenvironment
.tox .tox/
# Editors # Editors
*~ *~
.*.swp .*.swp
.bak .bak
# NetBeans user-specific build actions
nbactions.xml

57
openstack-object-storage-dev/bk_os-objectstorage-devguide.xml
View File

@ -1,30 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [ <!DOCTYPE book [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!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 POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]> ]>
<book xmlns="http://docbook.org/ns/docbook" <book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
@ -67,13 +43,24 @@
Application Programming Interface (API) v1.</para> Application Programming Interface (API) v1.</para>
</abstract> </abstract>
<revhistory> <revhistory>
<revision>
<date>2014-02-03</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Rewrote introduction and validated all code
examples.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision> <revision>
<date>2014-01-24</date> <date>2014-01-24</date>
<revdescription> <revdescription>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Added information about form &POST; and <para>Added information about form &POST; and temporary
temporary URL middleware.</para> URL middleware.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@ -159,7 +146,7 @@
<revdescription> <revdescription>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Fixed bugs 890435 and 907563 - Add/Update <para>Fixed bugs 890435 and 907563; Add/Update
Container Metadata and Expiring Objects. Changed to Container Metadata and Expiring Objects. Changed to
Maven 1.0.10.</para> Maven 1.0.10.</para>
</listitem> </listitem>
@ -196,9 +183,9 @@
<revdescription> <revdescription>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Removed references to ACL (Access Control List). <para>Removed references to Access Control List (ACL).
Fixed error in examples referring to X-Auth-Key where Fixed error in examples referring to <literal>X-Auth-Key</literal> where
it should be X-Auth-Token. Added section it should be <literal>X-Auth-Token</literal>. Added section
numbers.</para> numbers.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -210,7 +197,7 @@
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Expanded authentication information for UK <para>Expanded authentication information for UK
release. Added "delimiter" as a Query Parameter and release. Added <literal>delimiter</literal> as a query parameter and
server-side object copy example.</para> server-side object copy example.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -221,7 +208,7 @@
<revdescription> <revdescription>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Initial Release.</para> <para>Initial release.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@ -230,7 +217,7 @@
</info> </info>
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. --> <!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
<xi:include href="preface.xml"/> <xi:include href="preface.xml"/>
<xi:include href="ch_object-api-general.xml"/> <xi:include href="ch_object-api-concepts-and-features.xml"/>
<xi:include href="ch_object-api-storage-services.xml"/> <xi:include href="ch_object-api-operations.xml"/>
<xi:include href="ch_object-api-troubleshooting-examples.xml"/> <xi:include href="ch_object-api-examples.xml"/>
</book> </book>

27
openstack-object-storage-dev/ch_object-api-concepts-and-features.xml Normal file
View File

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter 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="ch_object-storage-dev-general-api">
<title>Object Storage API concepts and features</title>
<xi:include href="section_object-api-overview.xml"/>
<xi:include href="section_object-api-env-vars.xml"/>
<xi:include href="section_object-api-discoverability.xml"/>
<xi:include href="section_object-api-authentication.xml"/>
<xi:include href="section_object-api-response-formats.xml"/>
<xi:include href="section_object-api-versioning.xml"/>
<xi:include href="section_object-api-create-large-objects.xml"/>
<xi:include href="section_object-api-cors-headers.xml"/>
<xi:include href="section_object-api-compress-files.xml"/>
<xi:include href="section_object-api-browser-bypass.xml"/>
<xi:include href="section_object-api-expire-objects.xml"/>
<xi:include href="section_object-api-pseudo-hier-folders.xml"/>
<xi:include href="section_object-api-large-lists.xml"/>
<xi:include href="section_object-api-archive-auto-extract.xml"/>
<xi:include href="section_object-api-bulk-delete.xml"/>
<xi:include href="section_object-api-container-sync.xml"/>
<xi:include href="section_object-api-container-quotas.xml"/>
<xi:include href="section_object-api-tempurl.xml"/>
<xi:include href="section_object-api-formpost.xml"/>
<xi:include href="section_object-api-create-website.xml"/>
</chapter>

530
openstack-object-storage-dev/ch_object-api-examples.xml Normal file
View File

@ -0,0 +1,530 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</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>'>
]>
<chapter 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="examples">
<?dbhtml stop-chunking?>
<title>Object Storage API examples</title>
<para>This section introduces the cURL command language and
demonstrates how to use cURL commands to make Object Storage
API calls.</para>
<note>
<para>For more examples, see <link
xlink:href="http://api.openstack.org/api-ref-objectstorage.html"
>Object Storage API v1</link>.</para>
</note>
<xi:include href="section_object-api-curl-commands.xml"/>
<section xml:id="auth_examples">
<title>Authenticate</title>
<para>The following examples show you how to authenticate with
the Identity Service or Tempauth.</para>
<section xml:id="get_auth_token_keystone">
<title>Authenticate with the Identity Service</title>
<para>This section provides an overview of the
authentication process. For request and response
details, see <link
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/POST_authenticate_v2.0_tokens_.html"
>Authenticate</link> in the <citetitle>OpenStack
Identity Service API v2.0
Reference</citetitle>.</para>
<procedure>
<title>To authenticate with the Identity
Service</title>
<step>
<para>Send your credentials and a tenant ID or
tenant name to the Identity Service.</para>
<para>The response includes an authentication
token and service catalog.</para>
</step>
<step>
<para>Select the service catalog entry where
<literal>type</literal> is
<literal>object-store</literal>. Use the
<literal>publicURL</literal> endpoint,
which contains a URL with the full path to the
Object Storage account. The URL has the
format,
<uri>https://<replaceable>hostname</replaceable>/v1/<replaceable>account</replaceable></uri>.</para>
</step>
</procedure>
</section>
<section xml:id="get_auth_token_tempauth">
<title>Authenticate with Tempauth</title>
<procedure>
<title>To authenticate with Tempauth</title>
<step>
<para>Supply your user name and API access key in
headers, as follows:</para>
<itemizedlist>
<listitem>
<para><literal>X-Auth-User</literal>
header. Specify your Object Storage
user name.</para>
</listitem>
<listitem>
<para>
<literal>X-Auth-Key</literal> header.
Specify your access key.</para>
</listitem>
</itemizedlist>
<para>The following example shows a sample
request:</para>
<screen><prompt>#</prompt> <userinput>curl -i https://storage.clouddrive.com/v1/auth \
-H "X-Auth-User: jdoe" -H "X-Auth-Key: jdoepassword"</userinput></screen>
</step>
<step>
<para>When authentication succeeds, you receive a
<returnvalue>204</returnvalue>
<errortext>No Content</errortext> status code.
Any
<returnvalue>2<replaceable>nn</replaceable></returnvalue>
response indicates success.</para>
<para>The <literal>X-Auth-Token</literal> response
header contains the authentication token. The
<literal>X-Storage-Url</literal> response
header contains a URL that includes a full
path to the Object Storage account. The URL
has the format,
<uri>https://<replaceable>hostname</replaceable>/v1/<replaceable>account</replaceable></uri>.</para>
<para>The following example shows a sample
response:</para>
<screen><computeroutput>HTTP/1.1 204 No Content
Date: Mon, 12 Nov 2010 15:32:21
Server: Apache
X-Storage-Url: $publicURL
X-Auth-Token: $token
Content-Length: 0
Content-Type: text/plain; charset=UTF-8</computeroutput></screen>
</step>
</procedure>
</section>
</section>
<section xml:id="accounts">
<title>Account services</title>
<section xml:id="show-storage-usage">
<title>Show storage usage</title>
<para>To show how much data you have stored in the system
and the number of containers that you are using, send
a &HEAD; request to the Object Storage service.</para>
<para>Use the <parameter>-X</parameter> switch to specify
the &HEAD; method.</para>
<para>Use the <parameter>-i</parameter> switch to send the
HTTP response to terminal output.</para>
<para>Include the authentication token in the
<literal>X-Auth-Token</literal> header.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL -X HEAD -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 1
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4
Date: Fri, 17 Jan 2014 16:09:56 GMT</computeroutput></screen>
<para>The <literal>X-Account-Bytes-Used</literal> response
header shows the total bytes stored for the entire
account.</para>
<para>The <literal>X-Account-Container-Count</literal>
response header shows the number of containers in this
storage account.</para>
</section>
<section xml:id="list-containers">
<title>Show account details</title>
<para>This example shows account details, lists
containers, and asks for a JSON response:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT </computeroutput></screen>
<programlisting language="json">[
{
"count":0,
"bytes":0,
"name":"janeausten"
},
{
"count":1,
"bytes":14,
"name":"marktwain"
}
]</programlisting>
<para>This example shows account details, lists
containers, and asks for an XML response:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT </computeroutput></screen>
<programlisting language="xml"><xi:include parse="text" href="samples/container-get-details-resp.xml"/></programlisting>
</section>
</section>
<section xml:id="containers">
<title>Container services</title>
<section xml:id="acls">
<title>Container ACLs</title>
<para>The <literal>X-Container-Read</literal> metadata
header defines the access control list (ACL)
permissions for who can read objects in a container.
Before you set this header, only users with a valid
authentication token for the account can read objects
in that container.</para>
<para>List containers to show the absence of the
<literal>X-Container-Read</literal> header:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3
Content-Length: 0
Date: Tue, 15 Nov 2011 03:29:22 GMT</computeroutput></screen>
<para>Set the <literal>X-Container-Read</literal> header
to enable read and list access to everyone:</para>
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i \
-H "X-Auth-Token: $token" \
-H "X-Container-Read: .r:*,.rlistings" \
$publicURL/jerry</userinput></screen>
<screen><computeroutput>HTTP/1.1 202 Accepted
Content-Length: 58
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txf2befb56b1854a50995f710f2db48089
Date: Tue, 15 Nov 2011 03:33:16 GMT
202 Accepted
The request is accepted for processing.</computeroutput></screen>
<para>For a list of valid
<literal>X-Container-Read</literal> header values,
see <link
xlink:href="http://swift.openstack.org/misc.html#acls"
> ACLs</link>.</para>
<para>To see the metadata change:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5
Content-Length: 0
Date: Tue, 15 Nov 2011 03:33:36 GMT</computeroutput></screen>
<para>After you give everyone read access, anyone can
access any object in the container from a browser. To
do so, a user appends the object name to the
<literal>X-Storage-URL</literal> header value used
in the session. For example:</para>
<screen><userinput>$publicURL/jerry/cereal.jpg</userinput></screen>
</section>
<section xml:id="create_containers">
<title>Create a container</title>
<para>To create a container, issue a &PUT; request. You do
not need to check if a container already exists before
you issue a &PUT; request. The operation creates a
container or updates an existing container, as
appropriate.</para>
<para>Example requests and responses:</para>
<itemizedlist>
<listitem>
<para>Create a container with no metadata:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/steven -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: tx7f6b7fa09bc2443a94df0-0052d58b56
Date: Tue, 14 Jan 2014 19:09:10 GMT</computeroutput></screen>
</listitem>
<listitem>
<para>Create a container with metadata:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT</computeroutput></screen>
</listitem>
</itemizedlist>
<para>For a complete description of HTTP 1.1 header
definitions, see <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14"
>Header Field Definitions</link>.</para>
</section>
<section xml:id="large_list_containers_example">
<title>Page through large lists of containers</title>
<note>
<para>You can also use this technique to page through
large lists of objects.</para>
</note>
<para>For more information about how to page through large
lists of containers and objects, see <xref
linkend="large-lists"/>.</para>
<para>For a list of five container names, if you specify a
<parameter>limit</parameter> of two, two items are
returned. You can assume there are more names to list,
so make another request with a
<parameter>marker</parameter> of the last item
returned.</para>
<para>For example, assume the following list of container
names:</para>
<literallayout class="monospaced">apples
bananas
kiwis
oranges
pears</literallayout>
<procedure>
<title>To page through a large list of
containers</title>
<step>
<para>Use a <parameter>limit</parameter> of
two:</para>
<screen><userinput>GET $publicURL?limit=2
Host: storage.swiftdrive.com
X-Auth-Token: $token</userinput></screen>
<screen><computeroutput>apples
bananas</computeroutput></screen>
<para>Because two container names are returned,
there are more names to list.</para>
</step>
<step>
<para>Make another request with a
<parameter>marker</parameter> parameter
set to the name of the last item
returned:</para>
<screen><userinput>GET $publicURL?limit=2&amp;marker=bananas
Host: storage.swiftdrive.com
X-Auth-Token: $token</userinput></screen>
<screen><computeroutput>kiwis
oranges</computeroutput></screen>
<para>Again, two items are returned, and there
might be more.</para>
</step>
<step>
<para>Make another request with a
<parameter>marker</parameter> of the last
item returned:</para>
<screen><userinput>GET $publicURL?limit=2&amp;marker=oranges
Host: storage.swiftdrive.com
X-Auth-Token: $token</userinput></screen>
<screen><computeroutput>pears</computeroutput></screen>
<para>You now receive a one-item response, which
is fewer than the <parameter>limit</parameter>
number of names. This indicates that this is
the end of the list.</para>
</step>
<step>
<para>Use the <parameter>end_marker</parameter>
parameter to limit the result set to object
names that are less than the
<parameter>end_marker</parameter>
parameter value:</para>
<screen><userinput>GET $publicURL/?end_marker=oranges
Host: storage.swiftdrive.com
X-Auth-Token: $token</userinput></screen>
<screen><computeroutput>apples
bananas
kiwis</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="retrieve-copy-retrieve-objects">
<title>Get, copy, and delete objects</title>
<para>Now, retrieve an object that you previously
uploaded. First, remove the local copy:</para>
<screen><prompt>#</prompt> <userinput>ls -l</userinput></screen>
<screen><computeroutput>total 504
-rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
<screen><prompt>#</prompt> <interfacename>rm JingleRocky.jpg</interfacename>
<prompt>#</prompt> <userinput>ls -l</userinput></screen>
<screen><computeroutput>total 416
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput> </screen>
<para>Be sure not to use -i switch here because you want
the raw data, which you pipe to a file:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -H "X-Auth-Token: $token" $publicURL/dogs/JingleRocky.jpg > JingleRocky.jpg</userinput></screen>
<screen><prompt>#</prompt> <userinput>ls -l</userinput></screen>
<screen><computeroutput>total 504
-rw-r--r-- 1 petecj2 staff 44765 Nov 7 15:11 JingleRocky.jpg
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
<para>Next, Object Storage provides a facility to copy
objects from one container to another entirely on the
server side. To do this, you do a &PUT; with the
destination container and new object name while
passing a special X-Copy-From header and a
Content-Length of zero:</para>
<screen><prompt>#</prompt> <userinput>curl –X PUT -i -H "X-Auth-Token: $token" -H "X-Copy-From: /dogs/JingleRocky.jpg" -H "Content-Length: 0" $publicURL/elaine/JingleRocky.jpg</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 118
Content-Type: text/html; charset=UTF-8
Etag: f7d40eceffdd9c2ecab226105737b2a6
X-Copied-From: dogs/JingleRocky.jpg
Last-Modified: Mon, 07 Nov 2011 23:23:53 GMT
X-Trans-Id: tx244cd14df1b94d8c91ec5dcf8c5f9da4
Date: Mon, 07 Nov 2011 23:23:54 GMT
&lt;html>&lt;head>&lt;title>201 Created&lt;/title>&lt;/head>&lt;body>&lt;h1>201 Created&lt;/h1>&lt;br />&lt;br />&lt;/body>&lt;/html></computeroutput></screen>
<para>You can then confirm the new location of the object.
Issue a &GET; request with the destination
container:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/elaine/</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 1
X-Container-Bytes-Used: 44765
Accept-Ranges: bytes
Content-Length: 16
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd
Date: Mon, 07 Nov 2011 23:24:05 GMT
JingleRocky.jpg</computeroutput></screen>
<para>To delete an object from its container:</para>
<screen><prompt>#</prompt> <userinput>curl –X DELETE -i -H "X-Auth-Token: $token" $publicURL/elaine/JingleRocky.jpg</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txd45f04422b034e6f8447de400b78cbf3
Date: Mon, 07 Nov 2011 23:32:39 GMT</computeroutput></screen>
<para>List containers to confirm the deletion:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/elaine/</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: txc9b43bf4d896405eb9a88ca468bf7b2d
Content-Length: 0
Date: Mon, 07 Nov 2011 23:32:41 GMT</computeroutput></screen>
</section>
<section xml:id="container-metadata-and-delete-containers">
<title>Get container metadata and delete
containers</title>
<para>You can get at container metadata directly simply by
appending the name of the container to a HEAD
request:</para>
<screen><prompt>#</prompt> <userinput>curl –X HEAD -i \
-H "X-Auth-Token: $token" \
$publicURL/dogs</userinput>
<computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: tx3dd984f9482341dd97546e9d49d65e90
Content-Length: 0
Date: Mon, 07 Nov 2011 20:39:41 GMT</computeroutput></screen>
<para>To delete a container:</para>
<screen><prompt>#</prompt> <userinput>curl –X DELETE -i \
-H "X-Auth-Token: $token" \
$publicURL/george</userinput>
<computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx3fa3857f266f44319d9b8f4bf7ce7fc8
Date: Mon, 07 Nov 2011 20:42:58 GMT</computeroutput></screen>
<para>Then let's confirm the delete by listing the
containers again:</para>
<screen><prompt>#</prompt> <userinput>curl –X GET -i \
-H "X-Auth-Token: $token" \
$publicURL</userinput>
<computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 4
Accept-Ranges: bytes
Content-Length: 24
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx2475741852b849ce9403e382fe3f8015
Date: Mon, 07 Nov 2011 20:43:08 GMT
cosmo
dogs
elaine
jerry</computeroutput></screen>
</section>
</section>
<section xml:id="objects">
<title>Object services</title>
<section xml:id="static-large-objects-example">
<title>Create static large objects</title>
<para>To create a static large object:</para>
<orderedlist>
<listitem>
<para>Split the content into pieces.</para>
</listitem>
<listitem>
<para>Upload each piece into a segment
object.</para>
</listitem>
<listitem>
<para>Create a manifest object.</para>
</listitem>
</orderedlist>
<para>This example places the segment objects into the
<literal>segments</literal> container and the
manifest object into the <literal>images</literal>
container. Using a dedicated container for segment
objects is convenient.</para>
<para>Assuming you have already split the image into three
files, you can upload them. You have removed
non-essential response headers so you can see the
important details.</para>
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece1 $publicURL/segments/terrier-jpg-one</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 4000000
Etag: f7365c1419b4f349592c00bd0cfb9b9a</computeroutput></screen>
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece2 $publicURL/segments/terrier-jpg-two</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 2000000
Etag: ad81e97b10e870613aecb5ced52adbaa</computeroutput></screen>
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece3 $publicURL/segments/terrier-jpg-three</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 1000
Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3</computeroutput></screen>
<para>At this stage, you can create the manifest listing.
Notice that the size and ETag are copied from the
previous uploads. Create a file called
<filename>manifest.json</filename> with the
following content:</para>
<programlisting language="json"><xi:include parse="text" href="samples/manifest.json"/></programlisting>
<para>The final operation is to upload this content into a
manifest object. To indicate that this is a manifest
object, you must specify the
<parameter>multipart-manifest=put</parameter>
query parameter.</para>
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./manifest.json $publicURL/images/terrier-jpg?multipart-manifest=put</userinput></screen>
<para>Examine the static large object. Notice that its
size is the total size of all the segments:</para>
<screen><prompt>#</prompt> <userinput>curl –X HEAD -i -H "X-Auth-Token: $token" $publicURL/images/terrier-jpg</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 6001000
Etag: "0c922c37f915efb1c9b97e6328b3e660"</computeroutput></screen>
</section>
</section>
</chapter>

192
openstack-object-storage-dev/ch_object-api-general.xml
View File

@ -1,192 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter 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="ch_object-storage-dev-general-api">
<title>General API Information</title>
<section xml:id="authentication-object-dev-guide">
<title>Authentication</title>
<para>Client authentication is provided via a ReST interface
using the &GET; method, with <code>v1.0</code> supplied as
the path. Additionally, two headers are required,
<code>X-Auth-User</code> and <code>X-Auth-Key</code>
with values for the username and API Access Key
respectively.</para>
<para>Each ReST request against the OpenStack Object Storage
system requires the inclusion of a specific authorization
token HTTP x-header, defined as <code>X-Auth-Token</code>.
Clients obtain this token, along with the Cloud Servers
API URL, by first using an authentication service and
supplying a valid username and API access key.</para>
<simplesect>
<title>Request</title>
<para>To authenticate, you must supply your username and
API access key in x-headers:</para>
<para>
<itemizedlist spacing="compact">
<listitem>
<para>Use your OpenStack Object Storage
(Swift) username as the username for the
API. Place it in the
<code>X-Auth-User</code> x-header.
</para>
</listitem>
<listitem>
<para>Get your API access key from
authentication service you chose when
installing. You have some options for
auth, including tempauth (which is
included with Swift), swauth (an auth
service for Swift as WSGI middleware that
uses Swift itself as a backing store that
is provided via download from Github), the
OpenStack Identity Service (project named
Keystone), or you can use your own
authentication system. Place your access
key in the <code>X-Auth-Key</code>
x-header.</para>
</listitem>
</itemizedlist>
</para>
<para> </para>
<example>
<title>Authentication HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/auth-req.txt" parse="text"/></literallayout>
</example>
</simplesect>
<simplesect>
<title>Response</title>
<para>When authentication is successful, an HTTP status
204 (No Content) is returned with the
<code>X-Storage-Url</code> and
<code>X-Auth-Token</code> headers. Any 2xx
response is a good response. For example, a 202
response means the request has been accepted. Also,
additional <code>X-</code> headers may be returned.
These additional headers are related to other
Rackspace services and can be ignored. An HTTP status
of 401 (Unauthorized) is returned upon authentication
failure. All subsequent container/object operations
against OpenStack Object Storage should be made
against the URI specified in
<code>X-Storage-Url</code> and must include the
<code>X-Auth-Token</code> header.</para>
<example>
<title>Authentication HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/auth-resp.txt" parse="text"/></literallayout>
</example>
<para>The <code>X-Storage-Url</code> will need to be
parsed and used in the connection and request line of
all subsequent requests against Object Storage. In the
example response above, users connecting to OpenStack
Object Storage would send most container/object
requests with a host header of
<code>storage.swiftdrive.com</code> and the
request line's version and account as
<code>/v1/CF_xer7_34</code>. Note that
authentication tokens are valid for a 24 hour period
for many authentication configurations.</para>
</simplesect>
</section>
<section xml:id="overview-object-api">
<title>Overview of API Operations</title>
<para>The OpenStack Object Storage API is implemented as a set
of ReSTful (Representational State Transfer) web services.
All authentication and container/object operations can be
performed with standard HTTP calls. See the <link
xlink:href="http://en.wikipedia.org/wiki/Representational_State_Transfer"
>Representational State Transfer</link> on ReST for
more information</para>
<para>The following constraints apply to the ReST API's HTTP
requests:</para>
<itemizedlist>
<listitem>
<para>Maximum number of HTTP headers per request:
90</para>
</listitem>
<listitem>
<para>Maximum length of all HTTP headers: 4096
bytes</para>
</listitem>
<listitem>
<para>Maximum length per HTTP request line: 8192
bytes</para>
</listitem>
<listitem>
<para>Maximum length of HTTP request: 5
gigabytes</para>
</listitem>
<listitem>
<para>Maximum length of container name: 256
bytes</para>
</listitem>
<listitem>
<para>Maximum length of object name: 1024 bytes</para>
</listitem>
</itemizedlist>
<para>Container and object names must be UTF-8 encoded and then should be properly
URL-encoded prior to interacting with the ReST interface. You may be using an API
binding that performs the URL-encoding on your behalf. If so, do not URL-encode before
calling the API binding otherwise you will double-encode container and object names. The
length restrictions should be checked against the URL-encoded string.</para>
<para>Each ReST request against the OpenStack Object Storage
system requires the inclusion of a specific
<firstterm>authorization token</firstterm> HTTP header
defined as <code>X-Auth-Token</code>. Clients obtain this
token, along with the OpenStack Object Storage URLs, by
first using the Authentication service and supplying a
valid Username and API Access Key.</para>
<para><!--There are actually two different sets of ReST services that make up the full OpenStack Object Storage product. -->
The ReST service identified with
<code>X-Storage-Url</code> is used for managing the
data stored in the system. Example operations are creating
containers and uploading objects.
<!--The second ReST service is for managing the CDN feature of OpenStack Object Storage and is identified by <code>X-CDN-Management-Url</code>.--></para>
<para>In the following sections, the purpose of each HTTP
method depends upon which service the call is made
against. For example, a &PUT; request against
<code>X-Storage-Url</code> can be used to create a
container or upload an
object.<!--, while a &PUT; request against the <code>X-CDN-Management-Url</code> is used to CDN-enable a container--></para>
<para>The language-specific APIs mask this system separation
from the programmer. They simply create a container and
mark it <emphasis>public</emphasis> and it handles calling
out to the appropriate back-end services using the
appropriate ReST API.</para>
<note>
<para>All requests to authenticate and operate against
OpenStack Object Storage are performed using SSL over
HTTP (HTTPS) on TCP port 443.</para>
</note>
</section>
<xi:include href="section_object_api_tempurl.xml"/>
<xi:include href="section_object_api_formpost.xml"/>
</chapter>

59
openstack-object-storage-dev/ch_object-api-operations.xml Normal file
View File

@ -0,0 +1,59 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter 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="api-operations" role="api-reference">
<title>Object Storage API operations</title>
<para>Manage the accounts, containers, and objects in the Object
Storage system.</para>
<para>For a complete description of HTTP 1.1 header definitions, see
<link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14"
>Header Field Definitions</link>.</para>
<section xml:id="storage_account_services">
<title>Accounts</title>
<para>List containers for a specified account. Create, update,
and delete account metadata. Show account metadata.</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#account">
<wadl:method href="#showAccountDetails"/>
<wadl:method href="#updateAccountMeta"/>
<wadl:method href="#showAccountMeta"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_container_services">
<title>Containers</title>
<para>List objects in a specified container. Create, show
details for, and delete containers. Create, update, show,
and delete container metadata.</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#container">
<wadl:method href="#showContainerDetails"/>
<wadl:method href="#createContainer"/>
<wadl:method href="#deleteContainer"/>
<wadl:method href="#updateContainerMeta"/>
<wadl:method href="#showContainerMeta"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_object_services">
<title>Objects</title>
<para>Create, replace, show details for, and delete objects.
Copy objects with another object with a new or different name.
Update object metadata.</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#object">
<wadl:method href="#getObject"/>
<wadl:method href="#createOrReplaceObject"/>
<wadl:method href="#copyObject"/>
<wadl:method href="#deleteObject"/>
<wadl:method href="#showObjectMeta"/>
<wadl:method href="#updateObjectMeta"/>
</wadl:resource>
</wadl:resources>
</section>
</chapter>

82
openstack-object-storage-dev/ch_object-api-storage-services.xml
View File

@ -1,82 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- 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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter 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="ch_object-storage-dev-api-storage">
<title>API Operations for Storage Services</title>
<para>Use the ReST API to interact with the storage component of
OpenStack Object Storage. All requests are directed to the host
and URL described in the <code>X-Storage-Url</code> HTTP header
obtained during successful authentication.</para>
<para>Review the following requirements for using storage
services:</para>
<itemizedlist>
<listitem>
<para>Container names cannot exceed 256 bytes and cannot contain
the <literal>/</literal> character.</para>
</listitem>
<listitem>
<para>Object names cannot exceed 1024 bytes, and have no
character restrictions.</para>
</listitem>
<listitem>
<para>Object and container names must be UTF-8 encoded and then
URL-encoded to interact with the ReST API.</para>
</listitem>
</itemizedlist>
<para><!--<info>Added paragraph to forecast info structure -\- dsh -2012-03-09 </info>-->The
following sections describe the actions that you can perform in
the storage system.</para>
<itemizedlist>
<listitem>
<para><xref linkend="storage-account-services"/>. Actions that
you can perform at the account level of the storage system.
</para>
</listitem>
<listitem>
<para><xref linkend="storage-container-services"/>. Actions that
you can perform on containers.</para>
</listitem>
<listitem>
<para><xref linkend="Create_Static_Website-dle4000"/>. How to
use your swift account to create a static website.</para>
</listitem>
<listitem>
<para><xref linkend="storage-object-services"/>. Actions that
you can perform on objects.</para>
</listitem>
</itemizedlist>
<xi:include href="section_object-api-storage_account_svc.xml"/>
<xi:include href="section_object-api-storage-container-svc.xml"/>
<xi:include href="section_object-api-create-website.xml"/>
<xi:include href="section_object-api-storage-object-svc.xml"/>
</chapter>

993
openstack-object-storage-dev/ch_object-api-troubleshooting-examples.xml
View File

@ -1,993 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<chapter 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="ch_object-storage-dev-troubleshooting">
<title>Troubleshooting and Examples</title>
<para>This section introduces a command-line utility, cURL, and
demonstrates interacting with the ReST interfaces through that
utility.</para>
<section xml:id="using-curl-cli">
<title>Using cURL</title>
<para>cURL is a command-line tool which is available on most
UNIX®-like environments and Mac OS X® and can be
downloaded for Windows®. For more information on cURL,
visit <link xlink:href="http://curl.haxx.se/"
>http://curl.haxx.se/</link>.</para>
<para>cURL allows you to transmit and receive HTTP requests
and responses from the command-line or from within a shell
script. This makes it possible to work with the ReST API
directly without using one of the client APIs.</para>
<para>The following cURL command-line options will be
used</para>
<variablelist>
<title>cURL Command-Line Options</title>
<varlistentry>
<term><option>-X METHOD</option></term>
<listitem>
<para>Specify the HTTP method to request (&HEAD;,
&GET;, etc.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
<para>Dump HTTP response headers to stdout.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-H HEADER</option></term>
<listitem>
<para>Specify an HTTP header in the
request.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="authentication-examples-curl">
<title>Authentication</title>
<para>To use the ReST API, you must obtain a authorization
token, which you pass to each request in the
<code>X-Auth-Token</code> header. The following
example demonstrates how to use cURL to obtain the
authorization token and the URL of the storage
system.</para>
<example>
<title>cURL Authenticate</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>-i</option> \
<option>-H "X-Auth-Key: jdoesecretpassword"</option> \
<option>-H "X-Auth-User: jdoe"</option> \
<uri>https://auth.api.yourcloud.com/v1.0</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Date: Thu, 09 Jul 2009 15:31:39 GMT
Server: Apache/2.2.3
X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_343
X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae
Content-Length: 0
Connection: close
Content-Type: application/octet-stream</computeroutput></screen>
</example>
<para>The storage URL and authentication token are returned in
the headers of the response. After authentication, you can
use cURL to perform &HEAD;, &GET;, &DELETE;, &POST; and
&PUT; requests on the storage service.</para>
</section>
<section xml:id="determining-storage-useage">
<title>Determining Storage Usage</title>
<para>A &HEAD; request can be sent to the storage service to
determine how much data you have stored in the system and
the number of containers you are using. Use the
<code>-X</code> switch to specify the correct HTTP
method and the <code>-i</code> to dump the HTTP response
headers to terminal output (stdout).</para>
<example>
<title>cURL Get Storage Space</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Date: Thu, 09 Jul 2009 15:38:14 GMT
Server: Apache
X-Account-Container-Count: 22
X-Account-Bytes-Used: 9891628380
Content-Type: text/plain</computeroutput></screen>
</example>
<para>The HTTP request must include a header to specify the
authentication token. The HTTP headers in the response
indicate the number of containers in this storage account
and the total bytes stored for the entire account.</para>
</section>
<section xml:id="listing-and-creating-storage-containers">
<title>Listing and Creating Containers</title>
<para>The simplest operation for Object Storage is to simply
list the containers you have, which when you don't have
any containers yet isn't terribly exciting:</para>
<example>
<title>cURL List Storage Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 0
Accept-Ranges: bytes
X-Trans-Id: txe8ca5138ac8643ec84070543a0c9c91e
Content-Length: 0
Date: Mon, 07 Nov 2011 17:07:01 GMT</computeroutput></screen>
</example>
<para>So, you take the X-Auth-Token obtained from the
authentication operation, pass it as a header value,
execute the operation against the URL obtained from the
authentication operation, and force the GET verb with the
-X switch. What you get back tells you there aren't any
containers.</para>
<para>Next, let's create a container and then do the listing
again:</para>
<example>
<title>cURL Create Storage Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/george</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 18
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb25576385284476d9fa6c73835f21650
Date: Mon, 07 Nov 2011 17:44:20 GMT
201 Created</computeroutput></screen>
</example>
<para>Append the container name to the URL and force the PUT
verb. That creates a container, which we can now see when
we do a listing:</para>
<example>
<title>cURL List Storage Container After a
Creation</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 1
Accept-Ranges: bytes
Content-Length: 7
Content-Type: text/plain; charset=utf-8
X-Trans-Id: txaedd6b080626453399c9f5febbddb73b
Date: Mon, 07 Nov 2011 17:44:23 GMT
george</computeroutput></screen>
</example>
<para>You may have noticed the account metadata that comes
back from the listing call. As you'd guess, it'll tell you
how many objects you have, how much space you are using,
and how many containers you are using.</para>
</section>
<section xml:id="paging-containers">
<title>Paging Lists of Containers</title>
<para>If you have a large number of containers, it is
sometimes more convenient to page through them than
getting some big long list of them. If I create more
containers and then do a regular listing, here's what it
looks like with five containers:</para>
<example>
<title>cURL List Storage Container (long list)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 5
Accept-Ranges: bytes
Content-Length: 31
Content-Type: text/plain; charset=utf-8
X-Trans-Id: txb28795cc25b04f0dbce408dfa5a3cfc9
Date: Mon, 07 Nov 2011 19:03:06 GMT
cosmo
dogs
elaine
george
jerry</computeroutput></screen>
</example>
<para>Suppose I want a page size of 2, all I do is append a
""?limit=2"" to my URL:</para>
<example>
<title>cURL List Storage Container with Paging (first
page)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?limit=2</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 5
Accept-Ranges: bytes
Content-Length: 11
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx940ee02c1a65451e96a2a2532e3a7ce7
Date: Mon, 07 Nov 2011 19:05:30 GMT
cosmo
dogs</computeroutput></screen>
</example>
<para>Not surprisingly, I only get two containers. To get the
next page, you tell the system which item you last saw
with the "marker=" specifier:</para>
<example>
<title>cURL List Storage Container with Paging (later
pages)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?marker=dogs\&amp;limit=2</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 5
Accept-Ranges: bytes
Content-Length: 14
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx2a69f7ec38c34078a185c5875a4c0e34
Date: Mon, 07 Nov 2011 19:15:00 GMT
elaine
george</computeroutput></screen>
</example>
<para>Notice that I had to use \&amp; so that my bash shell
didn't try to interpret the &amp; as wanting to run
something in its own thread. With that in place, you get
the next page of items that appear after the
marker.</para>
</section>
<section xml:id="serialized-output">
<title>Serialized Output</title>
<para>In other situations, like if you are working on a
language binding on top of the REST API, you might want
more structured data back from the method calls. By
appending a "format=" and then choosing either json or
xml, you can get that structured data back you've been
dreaming about.</para>
<example>
<title>cURL List Storage Container (JSON output)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?format=json</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 5
Accept-Ranges: bytes
Content-Length: 187
Content-Type: application/json; charset=utf-8
X-Trans-Id: txd408573a51d2423c848cba191fbede9b
Date: Mon, 07 Nov 2011 19:17:33 GMT
[{"name":"cosmo", "count":0,"bytes":0},
{"name":"dogs","count":0,"bytes":0},
{"name":"elaine","count":0,"bytes":0},
{"name":"george","count":0,"bytes":0},
{"name":"jerry","count":0,"bytes":0}]</computeroutput></screen>
</example>
<example>
<title>cURL List Storage Container (XML output)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?format=xml</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 5
Accept-Ranges: bytes
Content-Length: 479
Content-Type: application/xml; charset=utf-8
X-Trans-Id: tx5e5685a15d0b406799b6a425b1150e4c
Date: Mon, 07 Nov 2011 19:17:38 GMT
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;account name="AUTH_a23f73d2-abfb-4656-af94-32ddec35dab8">
&lt;container>&lt;name>cosmo&lt;/name>&lt;count>0&lt;/count>&lt;bytes>0&lt;/bytes>&lt;/container>
&lt;container>&lt;name>dogs&lt;/name>&lt;count>0&lt;/count>&lt;bytes>0&lt;/bytes>&lt;/container>
&lt;container>&lt;name>elaine&lt;/name>&lt;count>0&lt;/count>&lt;bytes>0&lt;/bytes>&lt;/container>
&lt;container>&lt;name>george&lt;/name>&lt;count>0&lt;/count>&lt;bytes>0&lt;/bytes>&lt;/container>
&lt;container>&lt;name>jerry&lt;/name>&lt;count>0&lt;/count>&lt;bytes>0&lt;/bytes>&lt;/container>
&lt;/account></computeroutput></screen>
</example>
<para>The remainder of the examples in this document will use
the standard, non-serialized output but all operations
accept the format argument. You might notice that when you
use one of the formats, you get more information about the
containers. That's the per-container metadata, which is
covered in the next section.</para>
</section>
<section xml:id="container-metadata-and-delete-containers">
<title>Container Metadata and Deleting Containers</title>
<para>You can get at container metadata directly simply by
appending the name of the container to a HEAD
request:</para>
<example>
<title>cURL List Container Metadata</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: tx3dd984f9482341dd97546e9d49d65e90
Content-Length: 0
Date: Mon, 07 Nov 2011 20:39:41 GMT</computeroutput></screen>
</example>
<para>Not very exciting without any objects in the container,
but you get the idea. While you cannot update or delete
container metadata, you can delete a container:</para>
<example>
<title>cURL Delete Storage Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X DELETE</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/george</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx3fa3857f266f44319d9b8f4bf7ce7fc8
Date: Mon, 07 Nov 2011 20:42:58 GMT</computeroutput></screen>
</example>
<para>Then let's confirm the delete by listing the containers
again:</para>
<example>
<title>cURL List Containers After a Delete</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Account-Object-Count: 0
X-Account-Bytes-Used: 0
X-Account-Container-Count: 4
Accept-Ranges: bytes
Content-Length: 24
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx2475741852b849ce9403e382fe3f8015
Date: Mon, 07 Nov 2011 20:43:08 GMT
cosmo
dogs
elaine
jerry</computeroutput></screen>
</example>
</section>
<section xml:id="special-metadata-acls">
<title>Special Metadata: Container ACLs</title>
<para>A particularly important metadata element for containers
is X-Container-Read, which establishes the ACL permissions
on who can read objects in the container. Prior to being
set, the ACL logic default to only be accessible to
someone with a valid X-Auth-Token for the account in
question. Doing a simple listing of a container shows us
the absence of X-Container-Read in this default
situation:</para>
<example>
<title>cURL List Container Showing Lack of ACL</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3
Content-Length: 0
Date: Tue, 15 Nov 2011 03:29:22 GMT</computeroutput></screen>
</example>
<para>Now we'll set the X-Container-Read. For a full
explanation of valid values, see:
http://swift.openstack.org/misc.html#acls but for our
simple needs, we'll enable read access and listing access
to anybody:</para>
<example>
<title>cURL Setting an ACL on a Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-H "X-Container-Read: .r:*,.rlistings"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 202 Accepted
Content-Length: 58
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txf2befb56b1854a50995f710f2db48089
Date: Tue, 15 Nov 2011 03:33:16 GMT
202 Accepted
The request is accepted for processing.</computeroutput></screen>
</example>
<para>To see the metadata change, do a listing again:</para>
<example>
<title>cURL List Container Showing with an ACL</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5
Content-Length: 0
Date: Tue, 15 Nov 2011 03:33:36 GMT</computeroutput></screen>
</example>
<para>The side effect of giving anybody read access is that
any object in the container is now accessible from a
browser simply by entering the X-Storage-URL used
throughout the session and append the object name. For
example:</para>
<para>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry/cereal.jpg</para>
<para>would be the URL of an object named "cereal.jpg" in the
container "jerry" that has been made publicly accessible
using this method.</para>
</section>
<section xml:id="creating-objects">
<title>Creating Objects</title>
<para>Enough with containers already, let's start to upload
some objects. Suppose you had a local directory full of
dog pictures:</para>
<example>
<title>Sample File Listing</title>
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
<computeroutput>
total 504
-rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
</example>
<para>In order to put one of them in a container called "dogs"
with cURL, you'd do this:</para>
<example>
<title>Creating and Uploading an Object to a
Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-T JingleRocky.jpg</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 118
Content-Type: text/html; charset=UTF-8
Etag: f7d40eceffdd9c2ecab226105737b2a6
Last-Modified: Mon, 07 Nov 2011 22:51:29 GMT
X-Trans-Id: txd131cc897c78403daf5fad010d4d7152
Date: Mon, 07 Nov 2011 22:51:30 GMT
&lt;html>
&lt;head>
&lt;title>201 Created&lt;/title>
&lt;/head>
&lt;body>
&lt;h1>201 Created&lt;/h1>
&lt;br />&lt;br />
&lt;/body>
&lt;/html></computeroutput></screen>
</example>
<para>The object gets named from whatever we append to the URL
path beyond the container name and the -T switch lets us
name a file to push with the operation as the request
body. We can confirm the upload by checking the container
again:</para>
<example>
<title>cURL List Container Showing Newly Uploaded
Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 1
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 44765
Accept-Ranges: bytes
Content-Length: 16
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx83be89d4e1a34eacbfeebcdfc7a7f2e7
Date: Mon, 07 Nov 2011 22:56:25 GMT
JingleRocky.jpg</computeroutput></screen>
</example>
<para>Notice that the container metadata now reflects the
number of objects and the bytes match what we saw when we
did the directory listing. After uploading the other two
similarly, we get a full object listing:</para>
<example>
<title>cURL List Container Showing Multiple Newly Uploaded
Objects</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 3
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 252732
Accept-Ranges: bytes
Content-Length: 53
Content-Type: text/plain; charset=utf-8
X-Trans-Id: txae17dfa78da64117aaf07585a1b02115
Date: Mon, 07 Nov 2011 23:00:56 GMT
JingleRocky.jpg
RockyAndBuster.jpg
SittingBuster.jpg</computeroutput></screen>
</example>
</section>
<section xml:id="create_static_large_objects">
<title>Creating Static Large Objects</title>
<para>Creation of a static large object is done in several
steps. First we divide the content into pieces and upload
each piece into a segment object. Then we create a
manifest object. In this example, we will place the
segment objects into the "segments" container and the
manifest object into the "images" container. We are not
required to do this, but using a dedicated container for
segment objects is convenient.</para>
<para>Assuming we've already divided our image into three
files, let's upload them. We have removed non-essential
response headers so you can see the important
details.</para>
<example>
<title>Uploading first segment</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece1</option>
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-one</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 4000000
Etag: f7365c1419b4f349592c00bd0cfb9b9a</computeroutput></screen>
</example>
<example>
<title>Uploading second segment</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece2</option>
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-two</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 2000000
Etag: ad81e97b10e870613aecb5ced52adbaa</computeroutput></screen>
</example>
<example>
<title>Uploading final segment</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece3</option>
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-three</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 1000
Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3</computeroutput></screen>
</example>
<para>At this stage we are ready to create the manifest
listing. Notice that the size and ETag are copied from
uploads above. Lets use an editor to create a file called
<code>manifest.json</code> with the following
content:</para>
<example>
<title>Manifest List Example</title>
<screen><computeroutput> [
{
"path": "segments/terrier-jpg-one",
"etag": "f7365c1419b4f349592c00bd0cfb9b9a",
"size_bytes": 4000000
},
{
"path": "segments/terrier-jpg-two",
"etag": "ad81e97b10e870613aecb5ced52adbaa",
"size_bytes": 2000000
},
"path": "segments/terrier-jpg-three",
"etag": "00b046c9d74c3e8f93b320c5e5fdc2c3",
"size_bytes": 1000
{
}
]</computeroutput></screen>
</example>
<para>The final operation is to upload this content into a
manifest object. To indicate that this is a manifest
object, you need to specify the
<code>?multipart-manifest=put</code> query
string.</para>
<example>
<title>Uploading manifest object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./manifest.json</option>
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg?multipart-manifest=put</uri></userinput></screen>
</example>
<para>We can now examine our static large object. Notice that
the size is the total size of all the segments.</para>
<example>
<title>Examining a manifest object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option>
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 6001000
Etag: "0c922c37f915efb1c9b97e6328b3e660"</computeroutput></screen>
</example>
</section>
<section xml:id="paging-objects">
<title>Paging Lists of Objects</title>
<para>Exactly like listing containers, objects can be listed
in pages at a time using markers to denote pages. From the
previous example with 3 objects in the container "dogs",
the list can be paged with the "limit" query string
variable:</para>
<example>
<title>cURL List Objects (first page)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?limit=2</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 3
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 252732
Accept-Ranges: bytes
Content-Length: 35
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx5e00fa9fa895423198bc814cb0c6162d
Date: Tue, 15 Nov 2011 03:53:51 GMT
JingleRocky.jpg
RockyAndBuster.jpg</computeroutput></screen>
</example>
<para>And the second page fetched with:</para>
<example>
<title>cURL List Objects with Paging (later pages)</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?marker=RockyAndBuster.jpg\&amp;limit=2</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 3
X-Container-Read: .r:*,.rlistings
X-Container-Bytes-Used: 252732
Accept-Ranges: bytes
Content-Length: 18
Content-Type: text/plain; charset=utf-8
X-Trans-Id: txe1287a7179dc4dfd98610850a0fff157
Date: Tue, 15 Nov 2011 03:54:21 GMT
SittingBuster.jpg</computeroutput></screen>
</example>
</section>
<section xml:id="retrieve-copy-retrieve-objects">
<title>Retrieve, Copy, and Delete Objects</title>
<para>Now we'll retrieve an object previously uploaded. First,
we'll remove the local copy:</para>
<example>
<title>Removing Local Copies</title>
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
<computeroutput>
total 504
-rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg
$ rm JingleRocky.jpg
$ ls -l
total 416
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
</example>
<para>Be sure not to use -i switch here since what we want is
the raw data, which we'll then pipe to a file:</para>
<example>
<title>cURL Retrieve an Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg > JingleRocky.jpg</uri></userinput></screen>
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
<computeroutput>
total 504
-rw-r--r-- 1 petecj2 staff 44765 Nov 7 15:11 JingleRocky.jpg
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
</example>
<para>Next, Object Storage provides a facility to copy objects
from one container to another entirely on the server side.
To do this, you do a PUT with the destination container
and new object name while passing a special X-Copy-From
header and a Content-Length of zero:</para>
<example>
<title>cURL Server-side Copy an Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-H "X-Copy-From: /dogs/JingleRocky.jpg"</option> \
<option>-H "Content-Length: 0"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 118
Content-Type: text/html; charset=UTF-8
Etag: f7d40eceffdd9c2ecab226105737b2a6
X-Copied-From: dogs/JingleRocky.jpg
Last-Modified: Mon, 07 Nov 2011 23:23:53 GMT
X-Trans-Id: tx244cd14df1b94d8c91ec5dcf8c5f9da4
Date: Mon, 07 Nov 2011 23:23:54 GMT
&lt;html>
&lt;head>
&lt;title>201 Created&lt;/title>
&lt;/head>
&lt;body>
&lt;h1>201 Created&lt;/h1>
&lt;br />&lt;br />
&lt;/body>
&lt;/html></computeroutput></screen>
</example>
<para>You can then confirm the new location of the object. To
do this, you do a GET with the destination container to
see the listing of the object:</para>
<example>
<title>cURL Confirming the Server-side Copy an
Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 1
X-Container-Bytes-Used: 44765
Accept-Ranges: bytes
Content-Length: 16
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd
Date: Mon, 07 Nov 2011 23:24:05 GMT
JingleRocky.jpg</computeroutput></screen>
</example>
<para>To delete an object from its container, simply use the
DELETE verb:</para>
<example>
<title>cURL Delete an Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X DELETE</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txd45f04422b034e6f8447de400b78cbf3
Date: Mon, 07 Nov 2011 23:32:39 GMT</computeroutput></screen>
</example>
<para>Confirming the deletion by doing a container
listing:</para>
<example>
<title>cURL Confirming the Delete an Object</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: txc9b43bf4d896405eb9a88ca468bf7b2d
Content-Length: 0
Date: Mon, 07 Nov 2011 23:32:41 GMT</computeroutput></screen>
</example>
</section>
<section xml:id="object-metadata">
<title>Object Metadata</title>
<para>Objects can have whatever metadata keys/values you
choose. Simply POST an HTTP Header to the object in the
form of X-Object-Meta-&lt;key>: &lt;value>. Like
this:</para>
<example>
<title>cURL Set Object Metadata</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X POST</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-H "X-Object-Meta-Breed: Terrier pit bull mix""</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput> &lt;html>
&lt;head>
&lt;title>202 Accepted&lt;/title>
&lt;/head>
&lt;body>
&lt;h1>202 Accepted&lt;/h1>
The request is accepted for processing.&lt;br />&lt;br />
&lt;/body>
&lt;/html></computeroutput></screen>
</example>
<para>And then read the object metadata with a HEAD on the
object path:</para>
<example>
<title>cURL Reading Object Metadata</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput> HTTP/1.1 200 OK
X-Object-Meta-Breed: Terrier pit bull mix
Last-Modified: Tue, 08 Nov 2011 01:26:49 GMT
Etag: f7d40eceffdd9c2ecab226105737b2a6
Accept-Ranges: bytes
Content-Length: 44765
Content-Type: image/jpeg
X-Trans-Id: txa8bff9ad7ef844829103c1f9b8c20781
Date: Tue, 08 Nov 2011 01:29:35 GMT</computeroutput></screen>
</example>
</section>
<section xml:id="folders-directories">
<title>Pseudo-Hierarchical Folders/Directories</title>
<para>For the last section, we come to the most confusing
concept in Object Storage. In most storage systems, you
have the ability to create custom hierarchies of files so
that you can better organize them. On its surface, Object
Storage only gives you one level of hierarchy in the form
of containers. However, it turns out that you can get
creative with naming your objects to give yourself the
same effect as having hierarchical containers.</para>
<para>Let's start with a fresh container without any objects
in it:</para>
<example>
<title>cURL Create New Container for Folders</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 18
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txc78254a41b374b6ea10590d90874f769
Date: Wed, 16 Nov 2011 00:06:22 GMT
201 Created</computeroutput></screen>
</example>
<para>Now list the new container:</para>
<example>
<title>cURL Listing the New Container</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
X-Container-Object-Count: 0
X-Container-Bytes-Used: 0
Accept-Ranges: bytes
X-Trans-Id: tx49112200f7934c2bab1de3ae103c368e
Content-Length: 0
Date: Wed, 16 Nov 2011 00:06:26 GMT</computeroutput></screen>
</example>
<para>Next, add an object but prefix the name with the
hierarchy desired:</para>
<example>
<title>cURL Upload an Object with a Prefix</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-T JingleRocky.jpg</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos/terriers/JingleRocky.jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 118
Content-Type: text/html; charset=UTF-8
Etag: f7d40eceffdd9c2ecab226105737b2a6
Last-Modified: Wed, 16 Nov 2011 00:09:18 GMT
X-Trans-Id: txe34fdf2704f044e3a7102256386b1cb7
Date: Wed, 16 Nov 2011 00:09:19 GMT
&lt;html>
&lt;head>
&lt;title>201 Created&lt;/title>
&lt;/head>
&lt;body>
&lt;h1>201 Created&lt;/h1>
&lt;br />&lt;br />
&lt;/body>
&lt;/html></computeroutput></screen>
</example>
<para>Do it again with a different object and prefix:</para>
<example>
<title>cURL Upload a Different Object with a Different
Prefix</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<option>-T SittingBuster.jpg</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos/chihuahuas/SittingBuster.jpg</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 118
Content-Type: text/html; charset=UTF-8
Etag: e692e744c7180ee368166a24f1a2fa9b
Last-Modified: Wed, 16 Nov 2011 00:52:25 GMT
X-Trans-Id: txe229d03af5ea4d2ea1071def213c3f02
Date: Wed, 16 Nov 2011 00:52:25 GMT
&lt;html>
&lt;head>
&lt;title>201 Created&lt;/title>
&lt;/head>
&lt;body>
&lt;h1>201 Created&lt;/h1>
&lt;br />&lt;br />
&lt;/body>
&lt;/html></computeroutput></screen>
</example>
<para>Now list the container, revealing the prefixes:</para>
<example>
<title>cURL Listing a Container with Object Prefix</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 2
X-Container-Bytes-Used: 151868
Accept-Ranges: bytes
Content-Length: 54
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx8544a17e8b1e4da693145fb5f2e6db43
Date: Wed, 16 Nov 2011 00:53:43 GMT
chihuahuas/SittingBuster.jpg
terriers/JingleRocky.jpg</computeroutput></screen>
</example>
<para>If you want to perform hierarchical listings, with the
prefixes in place, you can use the "path" query string
variable:</para>
<example>
<title>cURL Listing a Container with a Path</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos?path=terriers</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 2
X-Container-Bytes-Used: 151868
Accept-Ranges: bytes
Content-Length: 25
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx3f1b9575d4de4a7d97ba3f9ad81923cc
Date: Wed, 16 Nov 2011 00:55:12 GMT
terriers/JingleRocky.jpg</computeroutput></screen>
</example>
<para>If you wanted to see what prefixes were in place, you
can use the "delimiter" query string variable to
distinguish prefix paths from object names:</para>
<example>
<title>cURL Listing a Container with a Delimiter</title>
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos?delimiter=/</uri></userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
X-Container-Object-Count: 2
X-Container-Bytes-Used: 151868
Accept-Ranges: bytes
Content-Length: 22
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx7222a3dd73fe44b888db4e58cc647d1e
Date: Wed, 16 Nov 2011 00:57:40 GMT
chihuahuas/
terriers/</computeroutput></screen>
</example>
<para>Using these in combination allows you to discover
directories within a particular path and then further
drill down based on the results.</para>
</section>
</chapter>

23
openstack-object-storage-dev/preface.xml
View File

@ -4,7 +4,7 @@
<!ENTITY ndash "&#x2013;"> <!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;"> <!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;"> <!ENTITY hellip "&#x2026;">
<!ENTITY nbsp "&#160;">
<!-- Useful for describing APIs --> <!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'> <!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'> <!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
@ -35,15 +35,14 @@ format="SVG" scale="60"/>
storage system is designed to provide a safe, secure, storage system is designed to provide a safe, secure,
automatically re-sizing and network-accessible way to store automatically re-sizing and network-accessible way to store
data. You can store an unlimited quantity of files and each data. You can store an unlimited quantity of files and each
file can be as large as 5 GBs, plus with large object file can be as large as 5&nbsp;GB, plus with large object
creation, you can upload and store objects of virtually any creation, you can upload and store objects of virtually any
size.</para> size.</para>
<para>OpenStack Object Storage allows users to store and retrieve <para>OpenStack Object Storage enables you to store and get files
files and content through a simple Web Service interface and content through the Representational State Transfer (REST)
(ReST: Representational State Transfer). There are also interface. There are also language-specific APIs that utilize
language-specific APIs that utilize the ReSTful API but make the RESTful API but make it much easier for developers to
it much easier for developers to integrate into their integrate into their applications.</para>
applications.</para>
<para>For more details on the OpenStack Object Storage service, <para>For more details on the OpenStack Object Storage service,
please refer to <link please refer to <link
xlink:href="http://docs.openstack.org/developer/swift/" xlink:href="http://docs.openstack.org/developer/swift/"
@ -56,7 +55,7 @@ format="SVG" scale="60"/>
<title>Intended Audience</title> <title>Intended Audience</title>
<para>This guide is intended to assist software developers who <para>This guide is intended to assist software developers who
want to develop applications using the OpenStack Object want to develop applications using the OpenStack Object
Storage API. It fully documents the ReST application Storage API. It fully documents the REST application
programming interface (API) that allows developers to programming interface (API) that allows developers to
interact with the storage components of the OpenStack interact with the storage components of the OpenStack
Object Storage system. To use the information provided Object Storage system. To use the information provided
@ -66,7 +65,7 @@ format="SVG" scale="60"/>
be familiar with:</para> be familiar with:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>ReSTful web services</para> <para>RESTful web services</para>
</listitem> </listitem>
<listitem> <listitem>
<para>HTTP/1.1</para> <para>HTTP/1.1</para>
@ -74,10 +73,10 @@ format="SVG" scale="60"/>
</itemizedlist> </itemizedlist>
<para>You can also find language-specific APIs in several <para>You can also find language-specific APIs in several
popular programming languages such as C#/.NET, Java, PHP, popular programming languages such as C#/.NET, Java, PHP,
Python, and Ruby. These APIs utilize the ReST API and are Python, and Ruby. These APIs utilize the REST API and are
provided to help developers rapidly integrate OpenStack provided to help developers rapidly integrate OpenStack
Object Storage support into their applications without Object Storage support into their applications without
needing to write at the ReST interface. Each API includes needing to write at the REST interface. Each API includes
its own documentation in its native format. For example, its own documentation in its native format. For example,
the Java API includes Javadoc documentation.</para> the Java API includes Javadoc documentation.</para>
</section> </section>

11
openstack-object-storage-dev/samples/bulk-delete-request.xml Normal file
View File

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<delete>
<number_deleted>2</number_deleted>
<number_not_found>4</number_not_found>
<errors>
<object>
<name>/v1/12345678912345/mycontainer</name>
<status>409 Conflict</status>
</object>
</errors>
</delete>

11
openstack-object-storage-dev/samples/bulk-delete-response.xml Normal file
View File

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<delete>
<number_deleted>2</number_deleted>
<number_not_found>4</number_not_found>
<errors>
<object>
<name>/v1/12345678912345/mycontainer</name>
<status>409 Conflict</status>
</object>
</errors>
</delete>

12
openstack-object-storage-dev/samples/container-get-details-resp.xml
View File

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<account name="MichaelBarton"> <account name="my_account">
<container> <container>
<name>test_container_1</name> <name>janeausten</name>
<count>2</count> <count>0</count>
<bytes>78</bytes> <bytes>0</bytes>
</container> </container>
<container> <container>
<name>test_container_2</name> <name>marktwain</name>
<count>1</count> <count>1</count>
<bytes>17</bytes> <bytes>14</bytes>
</container> </container>
</account> </account>

13
openstack-object-storage-dev/samples/get_containers_details_resp.xml Normal file
View File

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<account name="MichaelBarton">
<container>
<name>test_container_1</name>
<count>2</count>
<bytes>78</bytes>
</container>
<container>
<name>test_container_2</name>
<count>1</count>
<bytes>17</bytes>
</container>
</account>

17
openstack-object-storage-dev/samples/manifest.json Normal file
View File

@ -0,0 +1,17 @@
[
{
"path":"segments/terrier-jpg-one",
"etag":"f7365c1419b4f349592c00bd0cfb9b9a",
"size_bytes":4000000
},
{
"path":"segments/terrier-jpg-two",
"etag":"ad81e97b10e870613aecb5ced52adbaa",
"size_bytes":2000000
},
{
"path":"segments/terrier-jpg-three",
"etag":"00b046c9d74c3e8f93b320c5e5fdc2c3",
"size_bytes":1000
}
]

6
openstack-object-storage-dev/samples/object-delete-at-req.txt
View File

@ -1,5 +1 @@
PUT /<api version>/<account>/<container>/<object> HTTP/1.1 curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream"
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Type: image/jpeg
X-Delete-At: 1339429105

25
openstack-object-storage-dev/samples/server-post-req.xml Normal file
View File

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
imageRef="3afe97b2-26dc-49c5-a2cc-a2fc8d80c001" flavorRef="2"
name="api-test-server-xml2">
<metadata>
<meta key="My Server Name">API Test Server XML</meta>
</metadata>
<personality>
<file path="/etc/banner.txt">
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==</file>
</personality>
<networks>
<uuid>0ef47ac7-6797-4e01-8a47-ed26ec3aaa56</uuid>
<uuid>00000000-0000-0000-0000-000000000000</uuid>
<uuid>11111111-1111-1111-1111-111111111111</uuid>
</networks>
</server>

15
openstack-object-storage-dev/samples/server-post-resp.xml Normal file
View File

@ -0,0 +1,15 @@
<?xml version='1.0' encoding='UTF-8'?>
<server
xmlns:OS-DCF="http://docs.openstack.org/compute/ext/disk_config/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/compute/api/v1.1"
id="ed5c7754-29b6-45fa-96cb-ab64958c8c0a" adminPass="Dd5pNZtpVVQ3"
OS-DCF:diskConfig="AUTO">
<metadata/>
<atom:link
href="https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
rel="self"/>
<atom:link
href="https://dfw.servers.api.rackspacecloud.com/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
rel="bookmark"/>
</server>

114
openstack-object-storage-dev/section_object-api-archive-auto-extract.xml Normal file
View File

@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</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="archive-auto-extract">
<title>Auto-extract archive files</title>
<para>To discover whether your Object Storage system supports
this feature, see <xref linkend="discoverability"
/>. Alternatively, check with your service provider.</para>
<para>Use the auto-extract archive feature to upload a tar(1)
archive file.</para>
<para>The Object Storage system extracts files from the archive
file and creates an object.</para>
<section xml:id="archive-auto-extract-put">
<title>Auto-extract archive PUT request</title>
<para>To upload an archive file, you make a &PUT; request. Add
the
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
query parameter to indicate that you are uploading a
tar(1) archive file instead of normal content.</para>
<para>Valid values for the <replaceable>format</replaceable>
variable are <literal>tar</literal>,
<literal>tar.gz</literal>, or
<literal>tar.bz2</literal>.</para>
<para>The path you specify in the &PUT; request is a prefix
for the resulting object names.</para>
<para>For example, if the first object in the tar(1) archive
is <filename>/home/file1.txt</filename> and you specify
the
<filename>/v1/12345678912345/mybackup/castor/</filename>
path, the operation creates the
<filename>castor/home/file1.txt</filename> object in
the <literal>mybackup</literal> container in the
<literal>12345678912345</literal> account.</para>
<para>In the &PUT; request, you can specify the path
for:</para>
<itemizedlist>
<listitem>
<para>An account</para>
</listitem>
<listitem>
<para>Optionally, a specific container</para>
</listitem>
<listitem>
<para>Optionally, a specific object prefix</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="archive-auto-extract-create">
<title>Create an archive for auto-extract</title>
<para>You must use the tar(1) utility to create the tar(1)
archive file.</para>
<para>You can upload regular files but you cannot upload other
items, such as empty directories, symbolic links, and so
on.</para>
<para>You must UTF-8-encode the member names.</para>
<para>The archive auto-extract feature supports these
formats:</para>
<itemizedlist>
<listitem>
<para>The POSIX.1-1988 Ustar format.</para>
</listitem>
<listitem>
<para>The GNU tar format. Includes the long name, long
link, and sparse extensions.</para>
</listitem>
<listitem>
<para>The POSIX.1-2001 pax format.</para>
<para>Use gzip(1) or bzip2(1) to compress the
archive.</para>
<para>Use the <parameter>extract-archive</parameter>
query parameter to specify the format. Valid
values for this parameter are <literal>tar</literal>,
<literal>tar.gz</literal>, or
<literal>tar.bz2</literal>.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="archive-auto-extract-response">
<title>Auto-extract archive response: JSON</title>
<para>When Object Storage processes the request, it performs
multiple sub-operations. Even if all sub-operations fail,
the operation returns a <returnvalue>201</returnvalue>
<literal>Created</literal> status. You must examine the
response body to determine which members failed to result
in an object creation.</para>
<para>You can set the <literal>Accept</literal> request header
to one of these values, which defines the response format:</para>
<itemizedlist>
<listitem>
<para><literal>text/plain</literal>. Formats response
as plain text. If you omit the
<literal>Accept</literal> header,
<literal>text/plain</literal> is the
default.</para>
</listitem>
<listitem>
<para><literal>application/json</literal>. Formats
response as JSON.</para>
</listitem>
<listitem>
<para><literal>application/xml</literal> or
<literal>text/xml</literal>. Formats response
as XML.</para>
</listitem>
</itemizedlist>
<para>For more information, see <xref
linkend="archive-auto-extract-response"/>.</para>
</section>
</section>

96
openstack-object-storage-dev/section_object-api-authentication.xml Normal file
View File

@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<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="authentication">
<title>Authentication</title>
<para>The <emphasis role="italic">owner</emphasis> of an Object
Storage account controls access to that account and its
containers and objects. An owner is the user who has the
<literal>admin</literal> role for that tenant. The tenant
is also known as the project or account. As the account owner,
you can modify account metadata and create, modify, and delete
containers and objects.</para>
<para>To identify yourself as the account owner, include an
authentication token in the <literal>X-Auth-Token</literal>
header in the API request.</para>
<para>Depending on the token value in the
<literal>X-Auth-Token</literal> header, one of the
following actions occur:</para>
<itemizedlist>
<listitem>
<para><literal>X-Auth-Token</literal> contains the token
for the account owner.</para>
<para>The request is permitted and has full access to make
changes to the account.</para>
</listitem>
<listitem>
<para>The <literal>X-Auth-Token</literal> header is
omitted or it contains a token for a non-owner or a
token that is not valid.</para>
<para>The request fails with a <errorcode>401</errorcode>
<errortext>Unauthorized</errortext> or
<errorcode>403</errorcode>
<errortext>Forbidden</errortext> response.</para>
<para>You have no access to accounts or containers, unless
an access control list (ACL) explicitly grants
access.</para>
<para>The account owner can grant account and container
access to users through access control lists (ACLs).
For more information about ACLs, see <xref
linkend="acls"/>.</para>
</listitem>
</itemizedlist>
<para>The following table describes the authentication services
that you can use with Object Storage:</para>
<informaltable rules="all">
<thead>
<tr>
<th>Authentication service</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>OpenStack Identity Service
(Keystone)</para></td>
<td><para>The Object Storage account is synonymous
with the project or tenant ID.</para>
<para>For information about the Identity Service,
see <xref linkend="get_auth_token_keystone"
/>.</para>
</td>
</tr>
<tr>
<td>
<para>Tempauth middleware</para></td>
<td><para>Object Storage includes this middleware.
User and account management is performed in
the Object Storage system itself.</para>
<para>For information about Tempauth, see <xref
linkend="get_auth_token_tempauth"
/>.</para>
</td>
</tr>
<tr>
<td>
<para>swauth (in GitHub) or other custom
middleware</para></td>
<td><para>This custom middleware is modeled on
Tempauth, so usage is typically similar to
Tempauth.</para><para>Specifically, you use
the <literal>X-Auth-Token</literal> header to
pass an authentication token to an API
request.</para>
</td>
</tr>
</tbody>
</informaltable>
<para>Authentication tokens expire after a time period that the
authentication service defines. When a token expires, use of
the token causes requests to fail with a
<errorcode>401</errorcode>
<errortext>Unauthorized</errortext> response. To continue, you
must obtain a new token.</para>
</section>

28
openstack-object-storage-dev/section_object-api-browser-bypass.xml Normal file
View File

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8"?>
<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="content-disposition">
<title>Use the Content-Disposition metadata</title>
<para>To override the default behavior for a browser, use the
<literal>Content-Disposition</literal> header to specify
the override behavior and assign this header to an object. For
example, this header might specify that the browser use a
download program to save this file rather than show the file,
which is the default.</para>
<example>
<title>Override browser default behavior request: HTTP</title>
<para>This example assigns an attachment type to the
<literal>Content-Disposition</literal> header. This
attachment type indicates that the file is to be
downloaded as <literal>goodbye.txt</literal>:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "Content-Length: 14" -H "Content-Type: application/octet-stream" -H "Content-Disposition: attachment; filename=goodbye.txt"</userinput></screen>
<screen><computeroutput>HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txa9b5e57d7f354d7ea9f57-0052e17e13
Date: Thu, 23 Jan 2014 20:39:47 GMT
&lt;html>&lt;h1>Accepted&lt;/h1>&lt;p>The request is accepted for processing.&lt;/p>&lt;/html></computeroutput></screen>
</example>
</section>

162
openstack-object-storage-dev/section_object-api-bulk-delete.xml Normal file
View File

@ -0,0 +1,162 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</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="bulk-delete">
<title>Bulk delete</title>
<para>To discover whether your Object Storage system supports
this feature, see <xref linkend="discoverability"
/>. Alternatively, check with your service provider.</para>
<para>With bulk delete, you can delete up to 10,000 (configurable)
objects or containers in one request. The objects to be
deleted are listed in the body of a &POST; operation. Use
the <parameter>bulk-delete</parameter> query parameter to
indicate that you are performing a bulk delete operation
instead of a normal delete.</para>
<section xml:id="bulk-delete-request">
<title>Bulk delete request body</title>
<para>To perform a bulk delete operation, add the
<parameter>bulk-delete</parameter> query parameter to
the path. The path should be the account, such as
<literal>/v1/12345678912345</literal>), that contains
the objects and containers. You must set the
<literal>Content-Type</literal> request header to
<literal>text/plain</literal>.</para>
<para>In the request body, specify a list of objects or
containers names that are separated by a newline
character.</para>
<para>In addition:</para>
<itemizedlist>
<listitem>
<para>You must UTF-8-encode and then URL-encode the
names.</para>
</listitem>
<listitem>
<para>To indicate an object, specify the container and
object name as:
<literal><replaceable>CONTAINER_NAME</replaceable>/<replaceable>OBJECT_NAME</replaceable></literal></para>
</listitem>
<listitem>
<para>To indicate a container, specify the container
name as:
<literal><replaceable>CONTAINER_NAME</replaceable></literal></para>
</listitem>
<listitem>
<para>A container must be empty. If it contains
objects, Object Storage does not delete the
container.</para>
</listitem>
<listitem>
<para>You can include a maximum of 10,000 items in the
list. You can configure the maximum number of
items value.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="bulk-delete-response">
<title>Bulk delete response</title>
<para>When Object Storage processes the request, it performs
multiple sub-operations. Even if all sub-operations fail,
the operation returns a <returnvalue>200</returnvalue>
status. You must examine the response body to determine
which members failed to result in an object
deletion.</para>
<para>You can set the <literal>Accept</literal> request header
to one of these values, which defines the response
format:</para>
<itemizedlist>
<listitem>
<para><literal>text/plain</literal>. Formats response
as plain text. If you omit the
<literal>Accept</literal> header,
<literal>text/plain</literal> is the
default.</para>
</listitem>
<listitem>
<para><literal>application/json</literal>. Formats
response as JSON.</para>
</listitem>
<listitem>
<para><literal>application/xml</literal> or
<literal>text/xml</literal>. Formats response
as XML.</para>
</listitem>
</itemizedlist>
<para>For more information, see <xref
linkend="response-body-bulk-delete"/>.</para>
</section>
<section xml:id="response-body-bulk-delete">
<title>Response body for bulk operations</title>
<para>Some bulk operations, such as bulk delete and
auto-extract archive files, perform multiple
sub-operations. Some sub-operations might succeed while
others fail. The bulk operation returns a response body
that contains details that indicate which sub-operations
have succeeded and failed.</para>
<para>You can set the <literal>Accept</literal> request header
to define the response format.</para>
<para>The response body contains the following
information:</para>
<itemizedlist>
<listitem>
<para>The number of files actually deleted or created,
depending on context.</para>
</listitem>
<listitem>
<para>The number of not found objects. For bulk delete
only.</para>
</listitem>
<listitem>
<para>Errors. A list of object names and associated
error statuses for the objects that failed to
create or delete. The format depends on the value
you set in the <literal>Accept</literal>
header.</para>
</listitem>
</itemizedlist>
<para>The following auto-extract archive files example shows a
<literal>text/plain</literal> response body where no
failures occurred:</para>
<screen><computeroutput>Number Files Created: 10
Errors:</computeroutput></screen>
<para>The following auto-extract archive files example shows a
<literal>text/plain</literal> response where some
failures occurred. In this example, the Object Storage
system is configured to reject certain character strings
so that the <errorcode>400</errorcode>
<errortext>Bad Request</errortext> error occurs for any
objects that use the restricted strings.</para>
<screen><computeroutput>Number Files Created: 8
Errors:
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request</computeroutput></screen>
<para>The following example shows the failure response in
<literal>application/json</literal> format. This
example output has been reformatted with whitespace to
make it easier to read. The actual response has no such
whitespace.</para>
<programlisting language="json">{
"Number Files Created":1,
"Errors":[
[
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
"400 Bad Request"
],
[
"/v1/12345678912345/mycontainer/../image.gif",
"400 Bad Request"
]
]
}</programlisting>
<para>The following bulk delete example response is in
<literal>application/xml</literal> format. In this
example, the <literal>mycontainer</literal> container is
not empty, so it cannot be deleted.</para>
<programlisting language="xml"><xi:include parse="text" href="samples/bulk-delete-response.xml"/></programlisting>
</section>
</section>

20
openstack-object-storage-dev/section_object-api-compress-files.xml Normal file
View File

@ -0,0 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<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="file-compression">
<title>Use Content-Encoding metadata</title>
<para>When you create an object or update its metadata, you can
optionally set the <literal>Content-Encoding</literal>
metadata. This metadata enables you to indicate that the
object content is compressed without losing the identity of
the underlying media type (<literal>Content-Type</literal>) of
the file, such as a video.</para>
<example>
<title>Content-Encoding header request: HTTP</title>
<para>This example assigns an attachment type to the
<literal>Content-Encoding</literal> header that
indicates how the file is downloaded:</para>
<programlisting><xi:include href="samples/content-encoding-header-req.txt" parse="text"/></programlisting>
</example>
</section>

51
openstack-object-storage-dev/section_object-api-container-quotas.xml Normal file
View File

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!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:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="container-quotas">
<title>Container quotas</title>
<para>You can set quotas on the size and number of objects stored
in a container by setting the following metadata:</para>
<itemizedlist>
<listitem>
<para><literal>X-Container-Meta-Quota-Bytes</literal>. The
size, in bytes, of objects that can be stored in a
container.</para>
</listitem>
<listitem>
<para><literal>X-Container-Meta-Quota-Count</literal>. The
number of objects that can be stored in a container.
</para>
</listitem>
</itemizedlist>
<para>When you exceed a container quota, subsequent requests to
create objects fail with a <errorcode>413</errorcode>
<errortext>Request Entity Too Large</errortext> error.</para>
<para>The Object Storage system uses an <emphasis role="italic"
>eventual consistency</emphasis> model. When you create a
new object, the container size and object count might not be
immediately updated. Consequently, you might be allowed to
create objects even though you have actually exceeded the
quota.</para>
<para>At some later time, the system updates the container size
and object count to the actual values. At this time,
subsequent requests fails. In addition, if you are currently
under the <literal>X-Container-Meta-Quota-Bytes</literal>
limit and a request uses chunked transfer encoding, the system
cannot know if the request will exceed the quota so the system
allows the request. However, once the quota is exceeded, any
subsequent uploads that use chunked transfer encoding
fail.</para>
</section>

104
openstack-object-storage-dev/section_object-api-container-sync.xml Normal file
View File

@ -0,0 +1,104 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!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:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="container-sync">
<?dbhtml stop-chunking?>
<title>Container synchronization</title>
<para>To discover whether your Object Storage system supports
container synchronization, see <xref linkend="discoverability"
/>. Alternatively, check with your service provider.</para>
<para>Container synchronization enables you to synchronize the
contents of a source container with a destination container.
After you set up container synchronization, the system
automatically copies objects from the source container to the
destination container. Also, the system deletes objects in the
destination container that were deleted in the source
container.</para>
<para>The system copies objects in a way that object metadata is
retained, such as <literal>Last-Modified</literal> and any
custom metadata you might have set for the object.</para>
<para>You can configure the source and destination containers, as
follows:</para>
<itemizedlist>
<listitem>
<para>The source container can be on a different or the
same Object Storage system that the destination
container is on.</para>
</listitem>
<listitem>
<para>The destination container can be a source container
for synchronization for another destination container.
</para>
</listitem>
<listitem>
<para>The destination container can be the original source
container: both containers synchronize with each
other. Any object that you add to or delete from a
container is automatically copied to or deleted from
the other container.</para>
</listitem>
</itemizedlist>
<para>The Object Storage system performs the synchronization in
the background, and makes no guarantees about performance or
timeliness.</para>
<para>Some Object Storage features, such as large object creation,
might require the use of several containers. Container
synchronization handles each container separately; if your
object segments are located in a different container, they are
not transferred unless you also set up container
synchronization on that container. However, even if both the
manifest and segment containers are synchronized, there is no
guarantee that the manifest is transferred before the segment
objects. An attempt to download the large object from the
destination container might fail, be incomplete, or have
jumbled content. Object versioning is not supported.</para>
<para>To configure a <emphasis role="italic">source</emphasis>
container for synchronization, set the following metadata
headers:</para>
<itemizedlist>
<listitem>
<para><literal>X-Container-Sync-To</literal>. Set this
metadata header to the following value:</para>
<programlisting>//<replaceable>REALM</replaceable>/<replaceable>SYSTEM</replaceable>/<replaceable>DESTINATION_ACCOUNT</replaceable>/<replaceable>DESTINATION_CONTAINER_NAME</replaceable></programlisting>
<para>Your service provider can give you the appropriate
values for
<literal><replaceable>REALM</replaceable></literal>
and
<literal><replaceable>SYSTEM</replaceable></literal>.
The objects are sent to the
<literal><replaceable>DESTINATION_ACCOUNT</replaceable>/<replaceable>DESTINATION_CONTAINER_NAME</replaceable></literal>
container. These names can be different from the
source account and container names.</para>
</listitem>
<listitem>
<para><literal>X-Container-Sync-Key</literal>. Set this
metadata header to an arbitrary string value. This
value serves as a shared secret. Secure this value
just as you would a password.</para>
</listitem>
</itemizedlist>
<para>To configure a <emphasis role="italic"
>destination</emphasis> container to receive objects, set
the <literal>X-Container-Sync-Key</literal> metadata header to
the <literal>X-Container-Sync-Key</literal> value in the
source container.</para>
<note>
<para>To configure a destination container as the source
container for another destination container, set the
<literal>X-Container-Sync-To</literal> metadata header
as you would for a source container.</para>
</note>
</section>

48
openstack-object-storage-dev/section_object-api-cors-headers.xml Normal file
View File

@ -0,0 +1,48 @@
<?xml version="1.0" encoding="UTF-8"?>
<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="cors-headers">
<title>Assign CORS headers to requests</title>
<para>Cross-Origin Resource Sharing (CORS) is a specification that
defines how browsers and servers communicate across origins by
using HTTP headers, such as those assigned by Object Storage
API requests. The Object Storage API supports these headers.
For more information, see <link
xlink:href="http://www.w3.org/TR/access-control/"
>www.w3.org/TR/access-control/</link>.</para>
<itemizedlist>
<listitem>
<para>Access-Control-Allow-Credentials</para>
</listitem>
<listitem>
<para>Access-Control-Allow-Methods</para>
</listitem>
<listitem>
<para>Access-Control-Allow-Origin</para>
</listitem>
<listitem>
<para>Access-Control-Expose-Headers</para>
</listitem>
<listitem>
<para>Access-Control-Max-Age</para>
</listitem>
<listitem>
<para>Access-Control-Request-Headers</para>
</listitem>
<listitem>
<para>Access-Control-Request-Method</para>
</listitem>
<listitem>
<para>Origin</para>
</listitem>
</itemizedlist>
<para>You can assign these headers to only objects.</para>
<example>
<title>Assign CORS header request: HTTP</title>
<para>This example assigns the file origin to the
<literal>Origin</literal> header, which ensures that
the file originated from a reputable source:</para>
<literallayout class="monospaced"><xi:include href="samples/object-assign-cors-header-req.txt" parse="text"/></literallayout>
</example>
</section>

369
openstack-object-storage-dev/section_object-api-create-large-objects.xml Normal file
View File

@ -0,0 +1,369 @@
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY nbsp "&#160;">
<!-- 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="large-object-creation">
<title>Large objects</title>
<para>By default, the content of an object cannot be greater than
5&nbsp;GB. However, you can use segment objects and manifest
objects to store more content.</para>
<section xml:id="segment-objects">
<title>Segment objects</title>
<para>You can divide your content into segments, and upload
each segment into its own segment object. Segment objects
do not have any special features. You create, update,
download, and delete segment objects just as you would
normal objects.</para>
</section>
<section xml:id="manifest-objects">
<title>Manifest objects</title>
<para>A manifest object points to segment objects. When you
download a manifest object, Object Storage concatenates
the contents of the segment objects and returns this in
the response body of the request.</para>
<para>This behavior extends to the response headers returned
by &GET; and &HEAD; requests. The
<literal>Content-Length</literal> response header
value is the total size of all segment objects. Object
Storage calculates the <literal>ETag</literal> response
header value by taking the <literal>ETag</literal> value
of each segment, concatenating them together, and
returning the MD5 checksum of the result.</para>
<note>
<para>If you make a &COPY; request by using a manifest
object as the source, the new object is a normal, and
not a segment, object. If the total size of the source
segment objects exceeds 5&nbsp;GB, the &COPY; request
fails. However, you can make a duplicate of the
manifest object and this new object can be larger than
5&nbsp;GB.</para>
</note>
<para>The manifest object types are:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Static large
objects</emphasis>. The manifest object
content is an ordered list of the names of the
segment objects in JSON format.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Dynamic large
objects</emphasis>. The manifest object has no
content.</para>
<para>However, it has
<literal>X-Object-Manifest</literal> metadata
header. The value of this header is
<literal>&lt;container>/&lt;prefix></literal>,
where <literal>&lt;container></literal> is the
name of the container where the segment objects
are stored, and <literal>&lt;prefix></literal> is
a string that all segment objects have in
common.</para>
</listitem>
</itemizedlist>
<para>While both types of manifest objects have similar
behavior, the following table describes their
differences:</para>
<table rules="all">
<caption>Static and dynamic large objects</caption>
<thead>
<tr>
<th>Object type</th>
<th>End-to-end integrity</th>
<th>Upload order</th>
<th>Removal or addition of segment objects</th>
<th>Segment object size and number</th>
<th>Segment object container name</th>
<th>Manifest Object Metadata</th>
<th>Making a copy of the manifest object</th>
</tr>
</thead>
<tbody>
<tr>
<td><para>Static large object</para></td>
<td><para>Assured. The list of segments includes
the MD5 checksum (<literal>ETag</literal>)
of each segment. You cannot upload the
manifest object if the
<literal>ETag</literal> in the list
differs from the segment object already
uploaded. If a segment is somehow lost, an
attempt to download the manifest object
results in an error.</para></td>
<td><para>The segment objects must be uploaded
before the manifest object.</para></td>
<td><para>You cannot add or remove segment objects
from the manifest. However, you can create
a completely new manifest object of the
same name with a different manifest
list.</para></td>
<td><para>Segment objects must be at least 1&nbsp;MB in
size (by default). The final segment
object can be any size. At most 1000
segments are supported (by
default).</para></td>
<td><para>The manifest list includes the container
name of each object. Segment objects can
be in different containers.</para></td>
<td><para>The object has
<literal>X-Static-Large-Object</literal>
set to <literal>true</literal>. You do not
set this metadata directly. Instead the
system sets it when you &PUT; a static
manifest object.</para></td>
<td><para/></td>
</tr>
<tr>
<td><para>Dynamic large object</para></td>
<td><para>Not guaranteed. The eventual consistency
model means that although you have
uploaded a segment object, it might not
appear in the container listing until
later. If you download the manifest before
it appears in the container, it does not
form part of the content returned in
response to a &GET; request.</para></td>
<td><para>You can upload manifest and segment
objects in any order. You are recommended
to upload the manifest object after the
segments in case a premature download of
the manifest occurs. However, this is not
enforced.</para></td>
<td><para>You can upload new segment objects or
remove existing segments. The names must
simply match the
<literal>&lt;prefix></literal>
supplied in
<literal>X-Object-Manifest</literal>.</para></td>
<td><para>Segment objects can be of any
size.</para></td>
<td><para>All segment objects must be in the same
container</para></td>
<td><para>The <literal>X-Object-Manifest</literal>
value is the
<literal>&lt;container>/&lt;prefix></literal>
indicating where the segment objects are
located. You supply this request header in
the &PUT; operation</para></td>
<td><para>The &COPY; operation does not create a
manifest object. To duplicate a manifest
object, use the &GET; operation to read
the value of
<literal>X-Object-Manifest</literal>
and use this value in the
<literal>X-Object-Manifest</literal>
request header in a &PUT; operation. This
creates a new manifest object that shares
the same set of segment objects as the
original manifest object.</para></td>
</tr>
</tbody>
</table>
<section xml:id="dynamic-large-object-creation">
<title>Dynamic large objects</title>
<para>You must segment objects that are larger than 5&nbsp;GB
before you can upload them. You then upload the
segment objects like you would any other object and
create a dynamic large manifest object. The manifest
object tells Object Storage how to find the segment
objects that comprise the large object. The segments
remain individually addressable, but retrieving the
manifest object streams all the segments concatenated.
There is no limit to the number of segments that can
be a part of a single large object.</para>
<para>To ensure the download works correctly, you must
upload all the object segments to the same container
and ensure that each object name is prefixed in such a
way that it sorts in the order in which it should be
concatenated. You also create and upload a manifest
file. The manifest file is a zero-byte file with the
extra <literal>X-Object-Manifest</literal>
<code>&lt;container&gt;/&lt;prefix&gt;</code> header,
where <code>&lt;container&gt;</code> is the container
the object segments are in and
<code>&lt;prefix&gt;</code> is the common prefix
for all the segments. You must UTF-8-encode and then
URL-encode the container and common prefix in the
<literal>X-Object-Manifest</literal>
header.</para>
<para>It is best to upload all the segments first and then
create or update the manifest. With this method, the
full object is not available for downloading until the
upload is complete. Also, you can upload a new set of
segments to a second location and then update the
manifest to point to this new location. During the
upload of the new segments, the original manifest is
still available to download the first set of
segments.</para>
<example>
<title>Upload segment of large object request:
HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/large-object-upload-segment-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Upload segment of large object response:
HTTP</title>
<literallayout class="monospaced">s</literallayout>
</example>
<para>No response body is returned. A status code of
<returnvalue>2<replaceable>nn</replaceable></returnvalue>
(between 200 and 299, inclusive) indicates a
successful write; status <errorcode>411</errorcode>
<errortext>Length Required</errortext> denotes a
missing <literal>Content-Length</literal> or
<literal>Content-Type</literal> header in the request.
If the MD5 checksum of the data written to the storage
system does NOT match the (optionally) supplied ETag
value, a <errorcode>422</errorcode>
<errortext>Unprocessable Entity</errortext> response
is returned.</para>
<para>You can continue uploading segments like this
example shows, prior to uploading the manifest.</para>
<example>
<title>Upload next segment of large object request:
HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/large-object-upload-next-segment-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Upload next segment of large object response:
HTTP</title>
<literallayout class="monospaced">w</literallayout>
</example>
<para>Next, upload the manifest you created that indicates
the container the object segments reside within. Note
that uploading additional segments after the manifest
is created causes the concatenated object to be that
much larger but you do not need to recreate the
manifest file for subsequent additional
segments.</para>
<example>
<title>Upload manifest request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/upload-manifest-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Upload manifest response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/upload-manifest-resp.txt" parse="text"/></literallayout>
</example>
<para>The response's <literal>Content-Type</literal> for a
&GET; or &HEAD; on the manifest is the same as the
<literal>Content-Type</literal> set during the
&PUT; request that created the manifest. You can
easily change the <literal>Content-Type</literal> by
reissuing the &PUT; request.</para>
</section>
<section xml:id="static-large-objects">
<title>Static large objects</title>
<procedure>
<title>To create a static large object</title>
<step>
<para>Divide your content into pieces and create
(upload) a segment object to contain each
piece. You must record the <literal>ETag</literal>
response header returned by the&PUT;
operation. Alternatively, you can calculate
the MD5 checksum of the segment prior to
uploading and include this in the
<literal>ETag</literal> request header. This
ensures that the upload cannot corrupt your
data.</para>
</step>
<step>
<para>List the name of each segment object along
with its size and MD5 checksum in order.
Create a manifest object. You indicate that
this is a manifest object by including the
<parameter>?multipart-manifest=put</parameter> query
string at the end of the manifest object
name.</para>
</step>
</procedure>
<para>The body of the &PUT; request on the manifest object
comprises a json list, where each element contains the
following attributes:</para>
<itemizedlist>
<listitem>
<para><code>path</code>. The container and object
name in this format:
<code>&lt;container-name>/&lt;object-name></code></para>
</listitem>
<listitem>
<para><code>etag</code>. The MD5 checksum of the
content of the segment object. This value must
match the <literal>ETag</literal> of that
object.</para>
</listitem>
<listitem>
<para><code>size_bytes</code>. The size of the
segment object. This value must match the
<literal>Content-Length</literal> of that
object.</para>
</listitem>
</itemizedlist>
<example>
<title>Static large object manifest list</title>
<para>This example shows three segment objects. You
can use several containers and the object names do
not have to conform to a specific pattern, in
contrast to dynamic large objects.</para>
<literallayout class="monospaced"><xi:include href="samples/slo-manifest-example.txt" parse="text"/></literallayout>
</example>
<para>The <literal>Content-Length</literal> request header must
contain the length of the json content. Not the length
of the segment objects. However, after the &PUT;
operation completes, the <literal>Content-Length</literal>
metadata is set to the total length of all the object
segments. A similar situation applies to the
<literal>ETag</literal>. If used in the &PUT; operation,
it must contain the MD5 checksum of the json content.
The <literal>ETag</literal> metadata value is then set to be
the MD5 checksum of the concatenated <literal>ETag</literal>
values of the object segments. You can also set the
<literal>Content-Type</literal> request header and
custom object metadata.</para>
<para>When the &PUT; operation sees the
<parameter>?multipart-manifest=put</parameter>
query parameter, it reads the request body and verifies
that each segment object exists and that the sizes and
ETags match. If there is a mismatch, the
&PUT;operation fails.</para>
<para>If everything matches, the manifest object is
created. The <literal>X-Static-Large-Object</literal>
metadata is set to <literal>true</literal> indicating
that this is a static object manifest.</para>
<para>Normally when you perform a &GET; operation on the
manifest object, the response body contains the
concatenated content of the segment objects. To
download the manifest list, use the
<parameter>?multipart-manifest=get</parameter> query parameter.
The resulting list is not formatted the same as the
manifest you originally used in the &PUT;
operation.</para>
<para>If you use the &DELETE; operation on a manifest
object, the manifest object is deleted. The segment
objects are not affected. However, if you add the
<parameter>?multipart-manifest=delete</parameter> query parameter,
the segment objects are deleted and if all are
successfully deleted, the manifest object is also
deleted.</para>
<para>To change the manifest, use a &PUT; operation with
the <parameter>?multipart-manifest=put</parameter>
query parameter. This request creates a
new manifest object. You can
also update the object metadata in the usual
way.</para>
</section>
</section>
</section>

119
openstack-object-storage-dev/section_object-api-create-website.xml
View File

@ -1,56 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?> <?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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<section xmlns="http://docbook.org/ns/docbook" <section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="Create_Static_Website-dle4000"> xml:id="static-website">
<title>Create Static Website</title> <title>Create static website</title>
<para>You can use your swift account to create a static website. <para>To discover whether your Object Storage system supports
This mode is normally only active for anonymous requests. To this feature, see <xref linkend="discoverability"
use it with authenticated requests, set the header />. Alternatively, check with your service provider.</para>
<code>X-Web-Mode</code> to <code>TRUE</code> on the <para>You can use your Object Storage account to create a static
request. The <code>staticweb</code> filter should be added to website. This mode is normally only active for anonymous
the pipeline in your <code>/etc/swift/proxy-server.conf</code> requests, which provide no authentication token. To use it
file just after any auth middleware. Beneath the pipeline, the with authenticated requests, set the header
<code>staticweb</code> middleware configuration must be <literal>X-Web-Mode</literal> to <literal>TRUE</literal>
added. For example: on the request. To determine whether the static website
<literallayout class="monospaced"><xi:include href="samples/proxy-server-excerpt.conf" parse="text"/></literallayout> feature is enabled, contact your service provider.</para>
Your publicly readable containers will be checked for two <para>For example:</para>
headers, <code>X-Container-Meta-Web-Index</code> and <programlisting language="ini"><xi:include href="samples/proxy-server-excerpt.conf" parse="text"/></programlisting>
<code>X-Container-Meta-Web-Error</code>. (The latter <para>Your publicly readable containers are checked for two
headers, <literal>X-Container-Meta-Web-Index</literal> and
<literal>X-Container-Meta-Web-Error</literal>. (The latter
header is discussed below, under <link header is discussed below, under <link
linkend="Set_Error_Pages_for_Static_Website-dle4005">Set linkend="Set_Error_Pages_for_Static_Website-dle4005">Set
Error Pages for Static Website</link>.) With Error Pages for Static Website</link>.) With
<code>X-Container-Meta-Web-Index</code>, you determine the <literal>X-Container-Meta-Web-Index</literal>, you
index file (or default page served, such as determine the index file (or default page served, such as
<code>index.html</code>) displays your website. When <literal>index.html</literal>) displays your website. When
someone initially enters your site, they don't have to specify someone initially enters your site, they don't have to specify
the index file; index.html file displays automatically. If you the index file; index.html file displays automatically. If you
create sub-directories for your site by creating create sub-directories for your site by creating
@ -60,39 +34,41 @@ format="SVG" scale="60"/>
visits to the sub-directory return a 404 error.</para> visits to the sub-directory return a 404 error.</para>
<para>You also have the option of displaying a list of files in <para>You also have the option of displaying a list of files in
your pseudo-directory instead of a web page. You do this by your pseudo-directory instead of a web page. You do this by
setting the <code>X-Container-Meta-Web-Listings</code> header setting the <literal>X-Container-Meta-Web-Listings</literal>
to <code>TRUE</code>. You may add style to your file listing header to <literal>TRUE</literal>. You may add style to your
by setting <code>X-Container-Meta-Web-Listings-CSS:</code> to file listing by setting
a style sheet (for example, <code>lists.css</code>).</para> <literal>X-Container-Meta-Web-Listings-CSS:</literal> to a
style sheet (for example,
<literal>lists.css</literal>).</para>
<section xml:id="Examples_for_static_web-dle4025"> <section xml:id="Examples_for_static_web-dle4025">
<title>Static Web Middleware through swift</title> <title>Static Web Middleware through swift</title>
<example> <example>
<title>Make Container Publicly Readable</title> <title>Make Container Publicly Readable</title>
<para>Make the container publicly readable. Once the <para>Make the container publicly readable. Once the
container is publicly readable, you may access your container is publicly readable, you may access your
objects directly, but you will need to set the index objects directly, but you must set the index file to
file to browse the main site URL and its browse the main site URL and its
sub-directories.</para> sub-directories.</para>
<literallayout class="monospaced">swift post -r '.r:*' container</literallayout> <screen><prompt>$</prompt> <userinput>swift post -r '.r:*' container</userinput></screen>
</example> </example>
<example> <example>
<title>Set Site Index File</title> <title>Set Site Index File</title>
<para>Set the index file. In this case, <para>Set the index file. In this case,
<code>index.html</code> is the default file <literal>index.html</literal> is the default file
displayed when the site displays.</para> displayed when the site displays.</para>
<literallayout class="monospaced">swift post -m 'web-index:index.html' container</literallayout> <screen><prompt>$</prompt> <userinput>swift post -m 'web-index:index.html' container</userinput></screen>
</example> </example>
<example> <example>
<title>Enable File Listing</title> <title>Enable File Listing</title>
<para>Turn on file listing. If you do not set the index <para>Turn on file listing. If you do not set the index
file, list the objects in the container. Instructions file, list the objects in the container. Instructions
on styling the list with the CSS follow.</para> on styling the list with the CSS follow.</para>
<literallayout class="monospaced">swift post -m 'web-listings: true' container</literallayout> <screen><prompt>$</prompt> <userinput>swift post -m 'web-listings: true' container</userinput></screen>
</example> </example>
<example> <example>
<title>Enable CSS for File Listing</title> <title>Enable CSS for File Listing</title>
<para>Style the file listing.</para> <para>Style the file listing.</para>
<literallayout class="monospaced"><xi:include href="samples/file-listings-css-set-req.txt" parse="text"/></literallayout> <programlisting language="ini"><xi:include href="samples/file-listings-css-set-req.txt" parse="text"/></programlisting>
</example> </example>
</section> </section>
<section xml:id="Set_Error_Pages_for_Static_Website-dle4005"> <section xml:id="Set_Error_Pages_for_Static_Website-dle4005">
@ -100,24 +76,27 @@ format="SVG" scale="60"/>
<para>You can create and set custom error pages for visitors <para>You can create and set custom error pages for visitors
to your website; currently, only 401 (Unauthorized) and to your website; currently, only 401 (Unauthorized) and
404 (Not Found) errors are supported. To do this, set the 404 (Not Found) errors are supported. To do this, set the
metadata header, <code>X-Container-Meta-Web-Error</code>.</para> metadata header,
<literal>X-Container-Meta-Web-Error</literal>.</para>
<para>Error pages are served with the &lt;status&gt; code <para>Error pages are served with the &lt;status&gt; code
prepended to the name of the error page you set. For pre-pended to the name of the error page you set. For
instance, if you set instance, if you set
<code>X-Container-Meta-Web-Error</code> to <literal>X-Container-Meta-Web-Error</literal> to
<code>error.html</code>, 401 errors will display the <literal>error.html</literal>, 401 errors will display
page <code>401error.html</code>. Similarly, 404 errors the page <literal>401error.html</literal>. Similarly, 404
will display <code>404error.html</code>. You must have errors will display <literal>404error.html</literal>. You
both of these pages created in your container when you set must have both of these pages created in your container
the <code>X-Container-Meta-Web-Error</code> metadata, or when you set the
your site will display generic error pages.</para> <literal>X-Container-Meta-Web-Error</literal>
<para>Set the <code>X-Container-Meta-Web-Error</code> metadata metadata, or your site will display generic error
once for your entire static website.</para> pages.</para>
<para>Set the <literal>X-Container-Meta-Web-Error</literal>
metadata once for your entire static website.</para>
<example> <example>
<title>Set Error Pages for Static Website Request</title> <title>Set Error Pages for Static Website Request</title>
<literallayout class="monospaced"><xi:include href="samples/error-page-set-req.txt" parse="text"/></literallayout> <programlisting language="ini"><xi:include href="samples/error-page-set-req.txt" parse="text"/></programlisting>
</example> </example>
<para>Any 2<varname>xx</varname> response indicates success. <para>Any 2<varname>nn</varname> response indicates success.
</para> </para>
</section> </section>
</section> </section>

211
openstack-object-storage-dev/section_object-api-curl-commands.xml Normal file
View File

@ -0,0 +1,211 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<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="curl">
<title>cURL commands</title>
<para>cURL is a command-line tool that you can use to interact
with REST interfaces. cURL lets you to transmit and receive
HTTP requests and responses from the command line or a shell
script, which enables you to work with the API directly. It is
available for Linux distributions, Mac OS X, and Windows. For
information about cURL, see <link
xlink:href="http://curl.haxx.se/"
>http://curl.haxx.se/</link>.</para>
<para>To run the cURL request examples shown in this guide, copy
each example from the HTML version of this guide directly to
the command line or a script.</para>
<para>Before you can run these examples, you must set environment
variables. See <xref linkend="env-vars"/>.</para>
<para>This example cURL command shows account details and lists
containers in the account.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json \
-X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT</computeroutput>
</screen>
<para>The response, in JSON format, is:</para>
<programlisting language="json">[
{
"count":0,
"bytes":0,
"name":"janeausten"
},
{
"count":1,
"bytes":14,
"name":"marktwain"
}
]</programlisting>
<note>
<para>The carriage returns in the cURL request examples are
escaped with a backslash (<literal>\</literal>) character.
The escape character allows continuation of the command
across multiple lines. However, do not include the escape
character in the JSON or XML request body within the cURL
command.</para>
</note>
<para>The cURL examples in this guide use the following
command-line options:</para>
<table xml:id="curl_options" rules="all" width="75%">
<caption>cURL command-line options</caption>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<option>-d</option>
</td>
<td>
<para>Sends the specified data in a &POST; request
to the HTTP server. Use this option to send a
JSON or XML request body to the server.</para>
</td>
</tr>
<tr>
<td>
<option>-H</option>
</td>
<td>
<para>Specifies an extra HTTP header in the
request. You can specify any number of extra
headers. Precede each header with the
<option>-H</option> option.</para>
</td>
</tr>
<tr>
<td>
<option>-i</option>
</td>
<td>
<para>Includes the HTTP response headers in the
output.</para>
</td>
</tr>
<tr>
<td>
<option>-s</option>
</td>
<td>
<para>Silent or quiet mode. Does not show progress
or error messages. Makes cURL mute.</para>
</td>
</tr>
<tr>
<td>
<option>-T</option>
</td>
<td>
<para>Transfers the specified local file to the
remote URL.</para>
</td>
</tr>
<tr>
<td>
<option>-X</option>
</td>
<td>
<para>Specifies the request method to use when
communicating with the HTTP server. The
specified request is used instead of the
default method, which is &GET;.</para>
</td>
</tr>
</tbody>
</table>
<note xml:id="json_tool">
<title>json.tool</title>
<para>For commands that return a response, you can append the
following code to the command to call the json.tool to
pretty-print output:</para>
<programlisting language="bash" role="gutter: false">| python -m json.tool</programlisting>
<para>To use the <filename>json.tool</filename>, import the
<literal>json</literal> module. For information about
the <filename>json.tool</filename>, see <link
xlink:href="http://docs.python.org/2/library/json.html"
>json — JSON encoder and decoder</link>.</para>
<para>If you run a Python version older than 2.6, import the
<literal>simplejson</literal> module and use the
<filename>simplejson.tool</filename>. For information
about the <filename>simple.json</filename> tool, see <link
xlink:href="http://simplejson.googlecode.com/svn/tags/simplejson-2.0.9/docs/index.html"
>simplejson — JSON encoder and decoder</link>.</para>
<para>If you do not want to pretty-print JSON output, omit
this code.</para>
</note>
<section xml:id="curl_summary_xml">
<title>Example of an XML response</title>
<para>To request an XML response, append the
<literal>format=xml</literal> query parameter to the
request.</para>
<para>This example cURL command shows account information and
list containers in the account, and asks for the response
in XML:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=xml \
-X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT</computeroutput></screen>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;account name="my_account">
&lt;container>
&lt;name>janeausten&lt;/name>
&lt;count>0&lt;/count>
&lt;bytes>0&lt;/bytes>
&lt;/container>
&lt;container>
&lt;name>marktwain&lt;/name>
&lt;count>1&lt;/count>
&lt;bytes>14&lt;/bytes>
&lt;/container>
&lt;/account</programlisting>
</section>
</section>

66
openstack-object-storage-dev/section_object-api-discoverability.xml Normal file
View File

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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="discoverability">
<title>Discoverability</title>
<para>Your Object Storage system might not enable all features
that this document describes. These features are:</para>
<itemizedlist role="compact">
<listitem>
<para><xref linkend="large-object-creation"/></para>
</listitem>
<listitem>
<para><xref linkend="expire-objects"/></para>
</listitem>
<listitem>
<para><xref linkend="archive-auto-extract"/></para>
</listitem>
<listitem>
<para><xref linkend="bulk-delete"/></para>
</listitem>
<listitem>
<para><xref linkend="container-sync"/></para>
</listitem>
<listitem>
<para><xref linkend="container-quotas"/></para>
</listitem>
<listitem>
<para><xref linkend="tempurl"/></para>
</listitem>
<listitem>
<para><xref linkend="form-post"/></para>
</listitem>
<listitem>
<para><xref linkend="static-website"/></para>
</listitem>
</itemizedlist>
<para>To discover which features are enabled in your Object
Storage system, use the <literal>/info</literal> request.
However, your service provider might have disabled the
<literal>/info</literal> request, or you might be using an
older version that does not support the
<literal>/info</literal> request.</para>
<para>To use the <literal>/info</literal> request, send a &GET;
request using the <literal>/info</literal> path to the Object
Store endpoint as shown in this example:</para>
<screen><prompt>#</prompt> <userinput>curl https://storage.clouddrive.com/info</userinput></screen>
<para>This example shows a truncated response body:</para>
<programlisting language="json">{
"swift":{
"version":"1.11.0"
},
"staticweb":{
},
"tempurl":{
}
}</programlisting>
<para>This output shows that the Object Storage system has enabled
the static website and temporary URL features.</para>
</section>

2
openstack-object-storage-dev/section_object-api-dochistory.xml
View File

@ -29,7 +29,7 @@ format="SVG" scale="60"/>
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="doc_history"> xml:id="doc_history">
<title>Document Change History</title> <title>Document change history</title>
<para>This version of the document replaces and obsoletes <para>This version of the document replaces and obsoletes
all previous versions. The following table describes the latest changes:</para> all previous versions. The following table describes the latest changes:</para>
<?rax revhistory?> <?rax revhistory?>

38
openstack-object-storage-dev/section_object-api-env-vars.xml Normal file
View File

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<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="env-vars">
<title>Environment variables required to run examples</title>
<para>To run the cURL command examples for the Object Storage API
requests, set these environment variables:</para>
<itemizedlist>
<listitem>
<para><literal>publicURL</literal>. The public URL that is
the HTTP endpoint from where you can access Object
Storage. It includes the Object Storage API version
number and your account name. For example,
<code>https://23.253.72.207/v1/my_account</code>.</para>
</listitem>
<listitem>
<para><literal>token</literal>. The authentication token
for Object Storage.</para>
</listitem>
</itemizedlist>
<para>To obtain these values, run the <command>swift stat
-v</command> command.</para>
<para>As shown in this example, the public URL appears in the
<literal>StorageURL</literal> field, and the token appears
in the <literal>Auth Token</literal> field:</para>
<programlisting>StorageURL: https://23.253.72.207/v1/my_account
Auth Token: {token}
Account: my_account
Containers: 2
Objects: 3
Bytes: 47
Meta Book: MobyDick
X-Timestamp: 1389453423.35964
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes</programlisting>
</section>

61
openstack-object-storage-dev/section_object-api-expire-objects.xml Normal file
View File

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</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="expire-objects">
<title>Schedule objects for deletion</title>
<para>To discover whether your Object Storage system supports this
feature, see <xref linkend="discoverability"/>. Alternatively,
check with your service provider.</para>
<para>Scheduling an object for deletion is helpful for objects
that you do not want to permanently store, such as log files,
recurring full backups of a dataset, or documents or images
that become outdated at a specified future time.</para>
<para>To schedule an object for deletion, include one of these
headers with the &PUT; or &POST; request on the object:</para>
<itemizedlist>
<listitem>
<para><literal>X-Delete-After</literal></para>
<para>An integer value. Specifies the number of seconds in
the future when you want to delete the object.</para>
<para>This header is converted to an
<literal>X-Delete-At</literal> header that is set
to the sum of the <literal>X-Delete-After</literal>
value plus the current time, in seconds.</para>
</listitem>
<listitem>
<para><literal>X-Delete-At</literal></para>
<para>A UNIX Epoch timestamp, in integer form. For
example, <literal>1348691905</literal> represents
<literal>Wed, 26 Sep 2012 20:38:25 GMT</literal>.
Specifies the time when you want the object to expire,
not be served, and be deleted completely from the
object store.</para>
</listitem>
</itemizedlist>
<para>Use the &POST; method to assign expiration headers to
existing objects that you want expire.</para>
<simplesect>
<title>Delete object at specified time request: HTTP</title>
<para>In the example, the <code>X-Delete-At</code> header is
assigned a UNIX Epoch timestamp in integer form for Mon,
11 Jun 2012 15:38:25 GMT. Use <link
xlink:href="http://www.epochconverter.com/"
>http://www.epochconverter.com/</link> for example
timestamps and a batch converter.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream"</userinput></screen>
</simplesect>
<simplesect>
<title>Delete object after specified interval request:
HTTP</title>
<para>This example sets the <code>X-Delete-After</code> header
to a value in seconds that is equivalent to 10 days. After
this time, the object expires.</para>
<literallayout class="monospaced"><xi:include href="samples/object-delete-after-req.txt" parse="text"/></literallayout>
</simplesect>
</section>

3
openstack-object-storage-dev/section_object_api_formpost.xml → openstack-object-storage-dev/section_object-api-formpost.xml
View File

@ -13,6 +13,9 @@
xml:id="form-post"> xml:id="form-post">
<title>Form POST middleware</title> <title>Form POST middleware</title>
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<para>To discover whether your Object Storage system supports
this feature, see <xref linkend="discoverability"
/>. Alternatively, check with your service provider.</para>
<para>You can upload objects directly to the Object Storage system <para>You can upload objects directly to the Object Storage system
from a browser by using the form &POST; middleware. This from a browser by using the form &POST; middleware. This
middleware uses account secret keys to generate a middleware uses account secret keys to generate a

0
openstack-object-storage-dev/src/docbkx/object-api-language-bindings.xml → openstack-object-storage-dev/section_object-api-language-bindings.xml
View File

58
openstack-object-storage-dev/section_object-api-large-lists.xml Normal file
View File

@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
]>
<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="large-lists">
<title>Page through large lists of containers or objects</title>
<para>If you have a large number of containers or objects, you can
use the <parameter>marker</parameter>,
<parameter>limit</parameter>, and
<parameter>end_marker</parameter> parameters to control
how many items are returned in a list and where the list
starts or ends.</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold"><parameter>marker</parameter>
parameter</emphasis>. When you request a list of
containers or objects, Object Storage returns a
maximum of 10,000 names for each request. To get
subsequent names, you must make another request with
the <parameter>marker</parameter> parameter. Set the
<literal>marker</literal> parameter to the name of
the last item returned in the previous list. You must
URL-encode the <parameter>marker</parameter> value
before you send the HTTP request. Object Storage
returns a maximum of 10,000 names again.</para>
</listitem>
<listitem>
<para><emphasis role="bold"><parameter>limit</parameter>
parameter</emphasis>. To return fewer than 10,000
names, use the <parameter>limit</parameter> parameter.
If the number of names returned equals the specified
<parameter>limit</parameter> (or 10,000 if you
omit the <parameter>limit</parameter> parameter), you
can assume there are more names to list. If the number
of names in the list is exactly divisible by the
<parameter>limit</parameter> value, the last
request has no content.</para>
</listitem>
<listitem>
<para><emphasis role="bold"
><parameter>end_marker</parameter>
parameter</emphasis>. Limits the result set to
names that are less than the
<parameter>end_marker</parameter> parameter value.
You must URL-encode the
<parameter>end_marker</parameter> value before you
send the HTTP request.</para>
</listitem>
</itemizedlist>
<para>For examples of how to page through large lists, see <xref
linkend="examples"/>.</para>
</section>

257
openstack-object-storage-dev/section_object-api-overview.xml Normal file
View File

@ -0,0 +1,257 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY nbsp "&#160;">
<!-- Useful for describing APIs -->
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</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="object_storage_api_overview">
<title>Object Storage API overview</title>
<para>OpenStack Object Storage is an object-based storage system
that stores content and metadata as objects. You create,
modify, and get objects and metadata by using the Object
Storage API, which is implemented as a set of Representational
State Transfer (REST) web services.</para>
<para>For an introduction to OpenStack Object Storage, see <link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-object-storage.html"
>Object Storage</link> in the <citetitle>OpenStack Cloud
Administrator Guide</citetitle>.</para>
<para>You use the HTTPS (SSL) protocol to interact with Object
Storage, and you use standard HTTP calls to perform API
operations. You can also use language-specific APIs, which use
the RESTful API, that make it easier for you to integrate into
your applications.</para>
<para>To assert your right to access and change data in an
account, you identify yourself to Object Storage by using an
authentication token. To get a token, you present your
credentials to an authentication service. The authentication
service returns a token and the URL for the account. Depending
on which authentication service that you use, the URL for the
account appears in:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">OpenStack Identity
Service</emphasis>. The URL is defined in the
service catalog.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Tempauth</emphasis>. The URL
is provided in the <literal>X-Storage-Url</literal>
response header.</para>
</listitem>
</itemizedlist>
<para>In both cases, the URL is the full URL and includes the
account resource. For information about authentication, see
<xref linkend="authentication"/>.</para>
<para>The Object Storage API supports the standard, non-serialized
response format, which is the default, and both JSON and XML
serialized response formats. See <xref
linkend="serialized-response-formats"/>.</para>
<para>The Object Storage system organizes data in a hierarchy, as
follows:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Account</emphasis>. Represents
the top-level of the hierarchy.</para>
<para>Your service provider creates your account and you
own all resources in that account. The account defines
a namespace for containers. A container might have the
same name in two different accounts.</para>
<para>In the OpenStack environment,
<firstterm>account</firstterm> is synonymous with
a project or tenant.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Container</emphasis>. Defines
a namespace for objects. An object with the same name
in two different containers represents two different
objects. You can create any number of containers
within an account.</para>
<para>In addition to containing objects, you can also use
the container to control access to objects by using an
access control list (ACL). You cannot store an ACL
with individual objects.</para>
<para>In addition, you configure and control many other
features, such as object versioning, at the container
level. See <xref linkend="set-object-versions"
/>.</para>
<para>You can bulk-delete up to 10,000 containers in a
single request. See <xref linkend="bulk-delete"
/>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Object</emphasis>. Stores data
content, such as documents, images, and so on. You can
also store custom metadata with an object.</para>
<para>With the Object Storage API, you can:</para>
<itemizedlist>
<listitem>
<para>Store an unlimited number of objects. Each
object can be as large as 5&nbsp;GB, which is the
default. You can configure the maximum object
size.</para>
</listitem>
<listitem>
<para>Upload and store objects of any size with
large object creation. See <xref
linkend="large-object-creation"/>.</para>
</listitem>
<listitem>
<para>Use cross-origin resource sharing to manage
object security. See <xref
linkend="cors-headers"/>.</para>
</listitem>
<listitem>
<para>Compress files. See <xref
linkend="file-compression"/>.</para>
</listitem>
<listitem>
<para>Override browser behavior for an object. See
<xref linkend="content-disposition"
/>.</para>
</listitem>
<listitem>
<para>Schedule objects for deletion. See <xref
linkend="expire-objects"/>.</para>
</listitem>
<listitem>
<para>Bulk-delete up to 10,000 objects in a single
request. See <xref linkend="bulk-delete"
/>.</para>
</listitem>
<listitem>
<para>Auto-extract archive files. See <xref
linkend="archive-auto-extract"/>.</para>
</listitem>
<listitem>
<para>Generate a URL that provides time-limited
&GET; access to an object. See <xref
linkend="tempurl"/>.</para>
</listitem>
<listitem>
<para>Upload objects directly to the Object
Storage system from a browser by using form
&POST; middleware. See <xref
linkend="form-post"/>.</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>The account, container, and object hierarchy affects the way
you interact with the Object Storage API.</para>
<para>Specifically, the resource path reflects this structure and
has this format:</para>
<programlisting>/v1/{account}/{container}/{object}</programlisting>
<para>For example, for the <literal>flowers/rose.jpg</literal>
object in the <literal>images</literal> container in the
<literal>12345678912345</literal> account, the resource
path is:</para>
<programlisting>/v1/12345678912345/images/flowers/rose.jpg</programlisting>
<para>Notice that the object name contains the
<literal>/</literal> character. This slash does not
indicate that Object Storage has a sub-hierarchy called
<literal>flowers</literal> because containers do not store
objects in actual sub-folders. However, the inclusion of
<literal>/</literal> or a similar convention inside object
names enables you to create pseudo-hierarchical folders and
directories. See <xref
linkend="pseudo-hierarchical-folders-directories"
/>.</para>
<para>For example, if the endpoint for Object Storage is
<literal>objects.mycloud.com</literal>, the returned URL
is
<literal>https://objects.mycloud.com/v1/12345678912345</literal>.</para>
<para>To access a container, append the container name to the
resource path.</para>
<para>To access an object, append the container and the object
name to the path.</para>
<para>If you have a large number of containers or objects, you can
use query parameters to page through large lists of
containers or objects. Use the <parameter>marker</parameter>,
<parameter>limit</parameter>, and
<parameter>end_marker</parameter> query parameters to
control how many items are returned in a list and where the
list starts or ends. See <xref linkend="large-lists"/>.</para>
<para>Object Storage HTTP requests have the following default
constraints. Your service provider might use different default
values.</para>
<informaltable rules="all">
<thead>
<tr>
<th>Item</th>
<th>Maximum value</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Number of HTTP headers</td>
<td>90</td>
<td/>
</tr>
<tr>
<td>Length of HTTP headers</td>
<td>4096&nbsp;bytes</td>
<td/>
</tr>
<tr>
<td>Length per HTTP request line</td>
<td>8192&nbsp;bytes</td>
<td/>
</tr>
<tr>
<td>Length of HTTP request</td>
<td>5&nbsp;GB</td>
<td/>
</tr>
<tr>
<td>Length of container names</td>
<td>256&nbsp;bytes</td>
<td>Cannot contain the <literal>/</literal>
character.</td>
</tr>
<tr>
<td>Length of object names</td>
<td>1024&nbsp;bytes</td>
<td>By default, there are no character
restrictions.</td>
</tr>
</tbody>
</informaltable>
<para>You must UTF-8-encode and then URL-encode container and
object names before you call the API binding. If you use an
API binding that performs the URL-encoding for you, do not
URL-encode the names before you call the API binding.
Otherwise, you double-encode these names. Check the length
restrictions against the URL-encoded string.</para>
<para>These sections describe the operations that you can perform
with the Object Storage API:</para>
<itemizedlist>
<listitem>
<para><xref linkend="storage_account_services"/>. Use to
perform account-level tasks.</para>
<para>Lists containers for a specified account. Creates,
updates, and deletes account metadata. Shows account
metadata.</para>
</listitem>
<listitem>
<para><xref linkend="storage_container_services"/>. Use to
perform container-level tasks.</para>
<para>Lists objects in a specified container. Creates,
shows details for, and deletes containers. Creates,
updates, shows, and deletes container metadata.</para>
</listitem>
<listitem>
<para><xref linkend="storage_object_services"/>. Use to
perform object-level tasks.</para>
<para>Creates, replaces, shows details for, and deletes
objects. Copies objects with another object with a new
or different name. Updates object metadata.</para>
</listitem>
</itemizedlist>
</section>

94
openstack-object-storage-dev/section_object-api-pseudo-hier-folders.xml Normal file
View File

@ -0,0 +1,94 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!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="pseudo-hierarchical-folders-directories">
<title>Pseudo-hierarchical folders and directories</title>
<!-- reworked this section / as path and its elements / are not supported - dsh - 02-16-12 -->
<para>Although you cannot nest directories in OpenStack Object
Storage, you can simulate a hierarchical structure within a
single container by adding forward slash characters
(<literal>/</literal>) in the object name. To navigate the
pseudo-directory structure, you can use the
<code>delimiter</code> query parameter. this examples show
you how to use pseudo-hierarchical folders and
directories.</para>
<note>
<para>In this example, the objects reside in a container
called <code>backups</code>. Within that container, the
objects are organized in a pseudo-directory called
<code>photos</code>. Keep in mind that the container
name is not displayed in the example, but that it is a
part of the object URLs. For instance, the URL of the
picture <code>me.jpg</code> is
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.</para>
</note>
<example>
<title>List pseudo-hierarchical folders request: HTTP</title>
<para>To display a list of all the objects in the storage
container, use &GET; without a <code>delimiter</code> or
<code>prefix</code>.</para>
<literallayout class="monospaced">GET /v1/AccountString/backups</literallayout>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the requested list of the objects.</para>
<literallayout class="monospaced">photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg</literallayout>
<para>
<!-- The JIRA ticket / doc-97 subsumed / to this location - dsh - 02-03-12 -->Use
the delimiter parameter to limit the displayed results.
You can use any character as a delimiter. However, to use
<code>delimiter</code> with pseudo-directories, use
the parameter slash (<literal>/</literal>).</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?delimiter=/</literallayout>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the requested matching objects. Because you
use the slash, only the pseudo-directory
<code>photos/</code> displays. Keep in mind that the
returned values from a slash <code>delimiter</code> query
are not real objects. They have a content-type of
<literal>application/directory</literal> and are in
the <literal>subdir</literal> section of json and xml
results.</para>
<literallayout class="monospaced">photos/</literallayout>
<para>Use the <code>prefix</code> and <code>delimiter</code>
parameters to view the objects inside a pseudo-directory,
including further nested pseudo-directories.</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/&#38;delimiter=/</literallayout>
<para>The system returns status code 2xx (between 200 and 299,
inclusive) and the objects and pseudo-directories within
the top level pseudo-directory.</para>
<literallayout class="monospaced">photos/animals/
photos/me.jpg
photos/plants/</literallayout>
<para>You can create an unlimited number of nested
pseudo-directories. To navigate through them, use a longer
<code>prefix</code> parameter coupled with the
<code>delimiter</code> parameter. In this sample
output, there is a pseudo-directory called
<code>dogs</code> within the pseudo-directory
<code>animals</code>. To navigate directly to the
files contained within <code>dogs</code>, enter the
following command:</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/animals/dogs/&#38;delimiter=/ </literallayout>
<para>The system returns status code <returnvalue>2<replaceable>nn</replaceable></returnvalue> (between 200 and 299,
inclusive) and the objects and pseudo-directories within
the nested pseudo-directory.</para>
<literallayout class="monospaced">photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg</literallayout>
</example>
</section>

136
openstack-object-storage-dev/section_object-api-response-formats.xml Normal file
View File

@ -0,0 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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="serialized-response-formats">
<title>Serialized response formats</title>
<para>By default, the Object Storage API uses a
<literal>text/plain</literal> response format. In
addition, both JSON and XML data serialization response
formats are supported.</para>
<note>
<para>To run the cURL command examples, you must export <link
xlink:href="run_curl_commands">environment
variables</link>.</para>
</note>
<para>To define the response format, use one of these
methods:</para>
<informaltable rules="all">
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><para><code>format=<replaceable>format</replaceable></code>
query parameter</para></td>
<td>
<para>Append this parameter to the URL for a &GET;
request, where
<replaceable>format</replaceable> is
<code>json</code> or
<code>xml</code>.</para>
</td>
</tr>
<tr>
<td><para><literal>Accept</literal> request
header</para></td>
<td>
<para>Include this header in the &GET; request.
The valid header values are:</para>
<itemizedlist>
<listitem>
<para><code>text/plain</code>. Plain text
response format. The default.</para>
</listitem>
<listitem>
<para><code>application/json</code>. JSON
data serialization response
format.</para>
</listitem>
<listitem>
<para><code>application/xml</code> or
<code>text/xml</code>. XML data
serialization response format.</para>
</listitem>
</itemizedlist>
</td>
</tr>
</tbody>
</informaltable>
<example>
<title>JSON example with format query parameter</title>
<para>For example, this request uses the
<parameter>format</parameter> query parameter to ask
for a JSON response:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT</computeroutput></screen>
<para>Object Storage lists container names with additional
information in JSON format:</para>
<programlisting language="json">[
{
"count":0,
"bytes":0,
"name":"janeausten"
},
{
"count":1,
"bytes":14,
"name":"marktwain"
}
]</programlisting>
</example>
<example>
<title>XML example with Accept header</title>
<para>This request uses the <literal>Accept</literal> request
header to ask for an XML response:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H "Accept: application/xml; charset=utf-8"</userinput></screen>
<screen><computeroutput>HTTP/1.1 200 OK
Content-Length: 263
X-Account-Object-Count: 3
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 47
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txf0b4c9727c3e491694019-0052e03420
Date: Wed, 22 Jan 2014 21:12:00 GMT</computeroutput></screen>
<para>Object Storage lists container names with additional
information in XML format:</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;account name="AUTH_73f0aa26640f4971864919d0eb0f0880">
&lt;container>
&lt;name>janeausten&lt;/name>
&lt;count>2&lt;/count>
&lt;bytes>33&lt;/bytes>
&lt;/container>
&lt;container>
&lt;name>marktwain&lt;/name>
&lt;count>1&lt;/count>
&lt;bytes>14&lt;/bytes>
&lt;/container>
&lt;/account></programlisting>
<para>The remainder of the examples in this guide use
standard, non-serialized responses. However, all &GET;
requests that perform list operations accept the
<parameter>format</parameter> query parameter or
<literal>Accept</literal> request header.</para>
</example>
</section>

526
openstack-object-storage-dev/section_object-api-storage-container-svc.xml
View File

@ -1,518 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?> <?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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<section xmlns="http://docbook.org/ns/docbook" <section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="storage-container-services"> xml:id="storage-container-services">
<title>Storage Container Services</title> <title>Storage container services</title>
<para>You can perform the following operations for <para>Lists objects, creates and delete containers, and gets,
containers:</para> creates, updates, or deletes container metadata.</para>
<informaltable rules="all"> <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<thead> <wadl:resource
<tr> href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#container">
<td colspan="1">Verb</td> <wadl:method href="#listObjects"/>
<td colspan="2">URI</td> <wadl:method href="#createcontainer"/>
<td colspan="3">Description</td> <wadl:method href="#deletecontainer"/>
</tr> <wadl:method href="#retrievecontainermeta"/>
</thead> <wadl:method href="#updateacontainermeta"/>
<tbody> <wadl:method href="#deletecontainermeta"/>
<tr> </wadl:resource>
<td colspan="1">&GET;</td> </wadl:resources>
<td colspan="2"
>/<parameter>account</parameter>/<parameter>container</parameter></td>
<td colspan="3">Lists objects.</td>
</tr>
<tr>
<td colspan="1">&PUT;</td>
<td colspan="2"
>/<parameter>account</parameter>/<parameter>container</parameter></td>
<td colspan="3">Creates a container.</td>
</tr>
<tr>
<td colspan="1">&DELETE;</td>
<td colspan="2"
>/<parameter>account</parameter>/<parameter>container</parameter></td>
<td colspan="3">Deletes a container.</td>
</tr>
<tr>
<td colspan="1">&HEAD;</td>
<td colspan="2"
>/<parameter>account</parameter>/<parameter>container</parameter></td>
<td colspan="3">Gets container metadata.</td>
</tr>
</tbody>
</informaltable>
<variablelist>
<title>Optional headers for HEAD and GET</title>
<varlistentry>
<term><code>X-Newest</code></term>
<listitem>
<para>Set the optional <code>X-newest</code> header to
<code>True</code> in HEAD and GET requests to have
Object Storage return the latest version of the container.
If set to <code>True</code>, Object Storage queries all
replicas to return the most recent one. Without this header,
Object Storage responds faster after it finds one valid replica.
Because setting this header to <code>True</code> is more
expensive for the back end, use it only when it is
absolutely needed.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>All operations follow this format:</para>
<example>
<title>Storage Container Services HTTP Request</title>
<literallayout class="monospaced">METHOD /v1/&lt;account>/&lt;container> HTTP/1.1 </literallayout>
</example>
<section xml:id="list-objects">
<title>List Objects</title>
<para>&GET; operations against a storage container name are
performed to retrieve a list of objects stored in the
container. Additionally, there are a number of optional
query parameters that can be used to refine the list
results.</para>
<para>A request with no query parameters will return the full
list of object names stored in the container, up to 10,000
names. Optionally specifying the query parameters will
filter the full list and return a subset of
objects.</para>
<variablelist>
<title>Query Parameters</title>
<varlistentry>
<term><code>limit</code></term>
<listitem>
<para>For an integer value <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation>, limits the number of
results to at most <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation> values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>marker</code></term>
<listitem>
<para>Given a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return object names greater
in value than the specified marker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>end_marker</code></term>
<listitem>
<para>Given a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return object names less in
value than the specified marker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>prefix</code></term>
<listitem>
<para>For a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, causes the results to be
limited to object names beginning with the
substring <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>format</code></term>
<listitem>
<para>Specify either <code>json</code> or
<code>xml</code> to return the respective
serialized response.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>delimiter</code></term>
<listitem>
<para>For a character <inlineequation>
<mathphrase><emphasis>c</emphasis></mathphrase>
</inlineequation>, return all the object names
nested in the container (without the need for
the directory marker objects).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>path</code></term>
<listitem>
<para>For a string value<inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return the object names
nested in the pseudo path. Equivalent to
setting delimiter to '/' and prefix to the
path with a '/' on the end.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>List Objects HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/object-list-req.txt" parse="text"/></literallayout>
</example>
<para>A list of objects is returned in the response body, one
object name per line. The response will have a 2xx HTTP status
code (between 200 and 299 inclusive). If the container does
not exist, or if an incorrect account is specified, then a
response with a 404 (Not Found) status code will be
returned.</para>
<example>
<title>List Objects HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/object-list-resp.txt" parse="text"/></literallayout>
</example>
<section xml:id="serialized-list-output">
<title>Serialized List Output</title>
<para>If a <code>format=xml</code> or
<code>format=json</code> argument is appended to
the storage account URL, the service will serve
extended object information serialized in the chosen
format. Other than the <code>?format=xml|json</code>
parameter, it will return the same status/errors
codes. The sample responses below are formatted for
readability.</para>
<example>
<title>Get Objects Details HTTP and JSON
Request</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-json-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get Objects Details HTTP and JSON Response</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-json-resp.txt" parse="text"/></literallayout>
<programlisting language="json"><xi:include href="samples/objects-get-details-resp.json" parse="text"/></programlisting>
</example>
<example>
<title>Objects Details Request: XML</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-xml-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Objects Details Request: XML</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-xml-resp.txt" parse="text"/></literallayout>
<programlisting language="xml"><xi:include href="samples/objects-get-details-resp.xml" parse="text"/></programlisting>
</example>
</section>
<section xml:id="list-large-number-of-objects">
<title>Controlling a Large List of Objects</title>
<para>The system returns a maximum of 10,000 object names
per request. To retrieve subsequent object names,
another request must be made with the 'marker'
parameter. The marker indicates where the last list
left off and the system returns object names greater
than this marker, up to 10,000 again. Note that the
‘marker’ value should be URL encoded prior to sending
the HTTP request.</para>
<para>If 10,000 is larger than desired, a 'limit'
parameter may be given.</para>
<para>If the number of object names returned equals the
limit given (or 10,000 if no limit is given), it can
be assumed there are more object names to be listed.
If the container name list is exactly divisible by the
limit, the last request has no content.</para>
<example>
<title>List Large Number of Objects</title>
<para>For an example, let's use a listing of five
object names:</para>
<literallayout class="monospaced">gala
grannysmith
honeycrisp
jonagold
reddelicious</literallayout>
<para>We'll use a limit of two to show how things
work:</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-req.txt" parse="text"/></literallayout>
<para>Because we received two items back, we can
assume there are more object names to list. So, we
make another request with a marker of the last
item returned:</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-marker-req.txt" parse="text"/></literallayout>
<para>Again we have two items returned; there might be
more:</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-marker2-req.txt" parse="text"/></literallayout>
<para>Now we received less than the limit number of
object names, indicating that we have the complete
list.</para>
<para>By using <code>end_marker</code> we can limit
the result set to object names less than the given
value.</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-end-marker-req.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="pseudo-hierarchical-folders-directories">
<title>Pseudo-Hierarchical Folders and Directories</title>
<!-- reworked this section / as path and its elements / are not supported - dsh - 02-16-12 -->
<para>Although you cannot nest directories in OpenStack
Object Storage, you can simulate a hierarchical
structure within a single container by adding forward
slash characters (<literal>/</literal>) in the object
name. To navigate the pseudo-directory structure, you
may use the <code>delimiter</code> query parameter.
See the below examples for an illustration.</para>
<note>
<para>In the example below, the objects reside in a
container called <code>backups</code>. Within that
container, the objects are organized in a
pseudo-directory called <code>photos</code>. Keep
in mind that the container name is not displayed
in the example, but that it is a part of the
object URLs. For instance, the URL of the picture
<code>me.jpg</code> is
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.
</para>
</note>
<example>
<title>List Pseudo-Hierarchical Folders/Directories
Request</title>
<para>To display a list of all the objects in the
storage container, use &GET; without a
<code>delimiter</code> or <code>prefix</code>.</para>
<literallayout class="monospaced">GET /v1/AccountString/backups</literallayout>
<para>The system returns status code 2xx (between 200
and 299, inclusive) and the requested list of the
objects.</para>
<literallayout class="monospaced">photos/animals/cats/persian.jpg
photos/animals/cats/siamese.jpg
photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg
photos/me.jpg
photos/plants/fern.jpg
photos/plants/rose.jpg</literallayout>
<para>
<!-- The JIRA ticket / doc-97 subsumed / to this location - dsh - 02-03-12 -->Use
the delimiter parameter to limit the displayed
results. Any character may be used as a delimiter.
However, to use <code>delimiter</code> with
pseudo-directories, use the parameter slash
(<literal>/</literal>).</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?delimiter=/</literallayout>
<para>The system returns status code 2xx (between 200
and 299, inclusive) and the requested matching
objects. Because we use the slash, only the
pseudo-directory <code>photos/</code> displays. Keep
in mind that the returned values from a slash
<code>delimiter</code> query are not real objects.
They have a content-type of
<literal>application/directory</literal> and are in
the <literal>subdir</literal> section of json and xml
results.</para>
<literallayout class="monospaced">photos/</literallayout>
<para>Use the <code>prefix</code> parameter with the
<code>delimiter</code> parameter to view the
objects inside a pseudo-directory, including
further nested pseudo-directories.</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/&#38;delimiter=/</literallayout>
<para>The system returns status code 2xx (between 200
and 299, inclusive) and the objects and
pseudo-directories within the top level
pseudo-directory.</para>
<literallayout class="monospaced">photos/animals/
photos/me.jpg
photos/plants/ </literallayout>
<para>You can create an unlimited number of nested
pseudo-directories. To navigate through them, use
a longer <code>prefix</code> parameter coupled
with the <code>delimiter</code> parameter. In the
sample output below, there is a pseudo-directory
called <code>dogs</code> within the
pseudo-directory <code>animals</code>. In order to
navigate directly to the files contained within
<code>dogs</code>, enter the below command.</para>
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/animals/dogs/&#38;delimiter=/ </literallayout>
<para>The system returns status code 2xx (between 200
and 299, inclusive) and the objects and
pseudo-directories within the nested pseudo-directory.
</para>
<literallayout class="monospaced">photos/animals/dogs/corgi.jpg
photos/animals/dogs/poodle.jpg
photos/animals/dogs/terrier.jpg</literallayout>
</example>
</section>
</section>
<section xml:id="create-container">
<title>Create Container</title>
<para>&PUT; operations against a storage container are used to
create that container.</para>
<para>Containers are storage compartments for your data. The
URL encoded name must be less than 256 bytes and cannot
contain a forward slash '/' character.</para>
<para>Containers can be assigned custom metadata by including
additional HTTP headers on the &PUT; request. The custom
metadata is assigned to a container via HTTP headers
identified with the <code>X-Container-Meta-</code> prefix.</para>
<example>
<title>Create Container HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-create-req.txt" parse="text"/></literallayout>
</example>
<para>No content is returned. A status code of 201 (Created)
indicates that the container was created as requested.
Container &PUT; requests are idempotent and a code of 202
(Accepted) is returned when the container already existed.
If you request a &PUT; to a container with an
<code>X-Container-Meta-</code> prefix in the header,
your &GET;/&HEAD; request responses carry the metadata
prefix from the container in subsequent requests.</para>
<example>
<title>Create Container HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-create-resp.txt" parse="text"/></literallayout>
</example>
<para>Using custom container metadata, you can create information in the header to
effectively tag a container with metadata. The container metadata restrictions are the
same as object metadata: you can have 4096 bytes maximum overall metadata, 90 distinct
metadata items at the most. Each may have a 128 character name length with a maximum of
256 bytes in the value. Any valid UTF-8 encoded string value is allowed for metadata. In
addition for custom metadata, we <emphasis role="italic">recommend</emphasis> that you
URL-encode the header value. However, for non-custom metadata (such as
X-Versions-Location), you <emphasis role="italic">must</emphasis> UTF-8 encode and then
URL-encode values that contain a container or object name.</para>
<example>
<title>Container Create Container with Metadata HTTP
Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-create-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>No content is returned. A status code of 201 (Created)
indicates that the container was created as requested.
Container &PUT; requests are idempotent and a code of 202
(Accepted) is returned if the container existed prior to
the request. If you request a &PUT; to a container with an
<code>X-Container-Meta-</code> prefix in the header,
your &GET;/&HEAD; request responses carry the metadata
prefix from the container in subsequent requests.</para>
<example>
<title>Create Container with Metadata HTTP
Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-create-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="delete-container">
<title>Delete Container</title>
<para>&DELETE; operations against a storage container
permanently remove it. The container must be empty before
it can be deleted.</para>
<para>A &HEAD; request against the container can be used to
determine if it contains any objects.</para>
<example>
<title>Delete Container HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-delete-req.txt" parse="text"/></literallayout>
</example>
<para>No content is returned. A status code of 2xx (between
200 and 299, inclusive) indicates success, 404 (Not Found) is
returned if the requested container was not found, and a 409
(Conflict) if the container is not empty. No response body is
generated.</para>
<example>
<title>Delete Container HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-delete-resp.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="retrieve-container-metadata">
<title>Get Container Metadata</title>
<para>&HEAD; operations against a storage container are used
to determine the number of objects, and the total bytes of
all objects stored in the container. Since the storage
system is designed to store large amounts of data, care
should be taken when representing the total bytes response
as an integer; when possible, convert it to a 64-bit
unsigned integer if your platform supports that primitive
type.</para>
<example>
<title>Get Container Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>The HTTP status code will be 2xx (between 200 and 299,
inclusive) if the container exists, and 404 (Not Found) if it
does not. The object count and utilization are returned in the
<code>X-Container-Object-Count</code> and
<code>X-Container-Bytes-Used</code> headers
respectively.</para>
<example>
<title>Get Container Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="Update_Container_Metadata-d1e1900">
<title>Create or Update Container Metadata</title>
<para>You may create any custom or arbitrary metadata headers
as you find useful. They must, however, take the format
<code>X-Container-Meta-</code>.</para>
<para>To create or update the arbitrary container metadata,
use the &POST; query. Subsequent requests of the same
key/value pair overwrites the previous value.</para>
<example>
<title>Update Container Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-update-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>No response body is returned. A status code of 2xx
(between 200 and 299, inclusive) indicates success; status 404
(Not Found) is returned when the requested container does not
exist.</para>
<example>
<title>Update Container Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-update-metadata-resp.txt" parse="text"/></literallayout>
</example>
<para>To confirm your metadata changes, perform a &HEAD;
request on the container. Do not send the metadata in your
&HEAD; request.</para>
<example>
<title>View Container Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-view-metadata-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>View Container Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-view-metadata-resp.txt" parse="text"/></literallayout>
</example>
<!-- Note: using POST with null value should delete a metadata header, but
this method is not functional with all tools, so we are leaving it out for now.
A future patch may come where using "-" (dash) for the value will delete it. dsh - 2012-0309 -->
</section>
<section xml:id="delete-container-metadata">
<title>Delete Container Metadata</title>
<para>To delete a metadata header send an empty value for that
particular header, such as
<code>X-Container-Meta-Book:</code>.</para>
<para>If the tool you're using to communicate with Object
Storage doesn't support sending empty headers (older
versions of curl) send the header
"X-Remove-Container-Meta-<replaceable>name</replaceable>:
<replaceable>arbitrary value</replaceable>". For
example, send a header like
<code>X-Remove-Container-Meta-Book: x</code>. The
<emphasis>value</emphasis> (x in this example) is
ignored.</para>
<example>
<title>Delete Container Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-delete-metadata-req.txt" parse="text"/></literallayout>
<para>No response body is returned. A status code of 2xx
(between 200 and 299, inclusive) indicates success.</para>
</example>
</section>
</section> </section>

1053
openstack-object-storage-dev/section_object-api-storage-object-svc.xml
View File

File diff suppressed because it is too large Load Diff

332
openstack-object-storage-dev/section_object-api-storage_account_svc.xml
View File

@ -1,325 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?> <?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>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<section xml:id="storage-account-services" <section xml:id="storage-account-services"
xmlns="http://docbook.org/ns/docbook" xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Storage Account Services</title> <title>Storage account services</title>
<para>Perform the following operations at the account level of the <para>Lists containers and gets, creates, updates, or deletes
URL:</para> account metadata. You can perform these actions at the account
<informaltable rules="all"> level of the storage system.</para>
<thead> <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<tr> <wadl:resource
<td colspan="1">Verb</td> href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#account">
<td colspan="2">URI</td> <wadl:method href="#listContainers"/>
<td colspan="3">Description</td> <wadl:method href="#retrieveaccountmeta"/>
</tr> <wadl:method href="#updateaccountmeta"/>
</thead> <wadl:method href="#deleteaccountmeta"/>
<tbody> </wadl:resource>
<tr> </wadl:resources>
<td colspan="1">&GET;</td>
<td colspan="2">/<parameter>account</parameter></td>
<td colspan="3">Lists containers.</td>
</tr>
<tr>
<td colspan="1">&HEAD;</td>
<td colspan="2">/<parameter>account</parameter></td>
<td colspan="3">Gets account metadata.</td>
</tr>
<tr>
<td colspan="1">&POST;</td>
<td colspan="2">/<parameter>account</parameter></td>
<td colspan="3">Creates or updates account
metadata.</td>
</tr>
<tr>
<td colspan="1">&POST;</td>
<td colspan="2">/<parameter>account</parameter></td>
<td colspan="3">Deletes account metadata.</td>
</tr>
</tbody>
</informaltable>
<variablelist>
<title>Optional headers for HEAD and GET</title>
<varlistentry>
<term><code>X-Newest</code></term>
<listitem>
<para>Set the optional <code>X-newest</code> header to
<code>True</code> in HEAD and GET requests to have
Object Storage return the latest version of the account.
If set to <code>True</code>, Object Storage queries all
replicas to return the most recent one. Without this header,
Object Storage responds faster after it finds one valid replica.
Because setting this header to <code>True</code> is more
expensive for the back end, use it only when it is
absolutely needed.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example, the URL for the requests end with the OpenStack
Object Storage account string, as follows:</para>
<example>
<title>Storage Account Services HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/object-api-general-req.txt" parse="text"/></literallayout>
</example>
<section xml:id="s_listcontainers">
<title>List Containers</title>
<para>&GET; operations against the <code>X-Storage-Url</code>
for an account are performed to list storage containers
sorted by name. The sort order for the name is based on a
<link
xlink:href="http://www.sqlite.org/datatype3.html#collation"
>binary comparison</link>, a single built-in collating
sequence that compares string data by using the SQLite
memcmp() function, regardless of text encoding. The
following list describes the optional query parameters
that are supported with this request.</para>
<variablelist>
<title>Query Parameters</title>
<varlistentry>
<term><code>limit</code></term>
<listitem>
<para>For an integer value <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation>, limits the number of
results to <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation> values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>marker</code></term>
<listitem>
<para>Given a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return container names
greater in value than the specified
marker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>end_marker</code></term>
<listitem>
<para>Given a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return container names less
in value than the specified marker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>format</code></term>
<listitem>
<para>Specify either <code>json</code> or
<code>xml</code> to return the respective
serialized response.</para>
</listitem>
</varlistentry>
</variablelist>
<para>At this time, a <code>prefix</code> query parameter is
not supported at the account level.</para>
<example>
<title>List Containers HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/containers-list-req.txt" parse="text"/></literallayout>
</example>
<para>A list of containers is returned in the response body,
one container per line. The HTTP response's status code
will be 2xx (between 200 and 299, inclusive).</para>
<example>
<title>List Containers HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/containers-list-resp.txt" parse="text"/></literallayout>
</example>
<section xml:id="s_serializedlistoutput">
<title>Serialized List Output</title>
<para>If a <code>format=xml</code> or
<code>format=json</code> argument is appended to
the storage account URL, the service serves extended
container information serialized in the chosen format.
The sample responses are formatted for readability.</para>
<para>The following HTTP request asks for a JSON response,
so the response returns an HTTP header and a JSON
response.</para>
<example>
<title>Get Containers Details HTTP and JSON
Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-details-json-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get Containers Details HTTP and JSON
Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-json-resp.txt" parse="text"/></literallayout>
<programlisting language="json"><xi:include href="samples/container-get-details-resp.json" parse="text"/></programlisting>
</example>
<para>The following HTTP request asks for an XML response,
so the response returns an HTTP header and an XML
response.</para>
<example>
<title>Containers Details HTTP and XML Request</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-xml-resp.txt" parse="text"/></literallayout>
</example>
<example>
<title>Containers Details HTTP and XML
Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-xml-resp.txt" parse="text"/></literallayout>
<programlisting language="xml"><xi:include href="samples/container-get-details-resp.xml" parse="text"/></programlisting>
</example>
</section>
<section xml:id="s_list-large-number-containers">
<title>Controlling a Large List of Containers</title>
<para>The system returns a maximum of 10,000 container
names per request. To retrieve subsequent container
names, another request must be made with the 'marker'
parameter. The marker indicates where the last list
left off; the system returns container names greater
than this marker, up to 10,000 again. Note that the
‘marker’ value should be URL-encoded prior to sending
the HTTP request.</para>
<para>If 10,000 is larger than desired, use the 'limit'
parameter.</para>
<para>If the number of container names returned equals the
limit given (or 10,000 if no limit is given), you may
assume there are more container names.</para>
<example>
<title>List Large Number of Containers</title>
<para>For example, let's use a listing of five
container names:</para>
<literallayout class="monospaced">apples
bananas
kiwis
oranges
pears</literallayout>
<para>We'll use a limit of two to show how things
work:</para>
<literallayout class="monospaced"><xi:include href="samples/large-container-list-req.txt" parse="text"/></literallayout>
<literallayout class="monospaced">apples
bananas</literallayout>
<para>Because we received two items back, we can
assume there are more container names to list, so
we make another request with a marker of the last
item returned:</para>
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter-req.txt" parse="text"/></literallayout>
<literallayout class="monospaced">kiwis
oranges</literallayout>
<para>Again, two items are returned; there might be
more:</para>
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter2-req.txt" parse="text"/></literallayout>
<literallayout class="monospaced">pears</literallayout>
<para>With this one-item response we received less
than the limit number of container names,
indicating that this is the end of the
list.</para>
<para>By using <code>end_marker</code> we can limit
the result set to container names less than the
given value.</para>
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter-end-marker-req.txt" parse="text"/></literallayout>
<literallayout class="monospaced">apples
bananas
kiwis</literallayout>
</example>
</section>
</section>
<section xml:id="retrieve-account-metadata">
<title>Get Account Metadata</title>
<para>&HEAD; operations against an account are performed to
retrieve the number of containers and the total bytes
stored in OpenStack Object Storage for the account. This
information is returned in two custom headers,
<code>X-Account-Container-Count</code> and
<code>X-Account-Bytes-Used</code>. Since the storage
system is designed to store large amounts of data, care
should be taken when representing the total bytes response
as an integer; when possible, convert it to a 64-bit
unsigned integer if your platform supports that primitive
type.</para>
<example>
<title>Get Account Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/account-get-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>The HTTP return code will be 2xx (between 200 and 299,
inclusive) if the request succeeds. A 401 (Unauthorized)
will be returned for an invalid account or access
key.</para>
<example>
<title>Get Account Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/account-get-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="create-update-account-metadata">
<title>Create or Update Account Metadata</title>
<para>You can associate custom metadata headers with the
account level URI. These headers must take the format
<code>X-Account-Meta-*</code>.</para>
<para>To create or update an account metadata header use the
&POST; query. Subsequent requests for the same key/value
pair overwrite the previous value.</para>
<example>
<title>Update Account Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/account-update-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>No response body is returned. A status code of 2xx
(between 200 and 299, inclusive) indicates success.</para>
<example>
<title>Update Account Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/account-update-metadata-resp.txt" parse="text"/></literallayout>
</example>
<para>To confirm your metadata changes, perform a &HEAD;
request on the account. Do not send the metadata in your
&HEAD; request.</para>
<example>
<title>View Account Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/account-view-metadata-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>View Account Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/account-view-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
<section xml:id="delete-account-metadata">
<title>Delete Account Metadata</title>
<para>To delete a metadata header, send an empty value for
that particular header, such as for the
<code>X-Account-Meta-Book</code> header.</para>
<para>If the tool you use to communicate with Object Storage,
such as older versions of cURL, does not support empty
headers, send the
<literal>X-Remove-Account-Meta-</literal><replaceable>name</replaceable><literal>:</literal>
<replaceable>arbitrary value</replaceable> header. For
example, <code>X-Remove-Account-Meta-Book: x</code>. The
<replaceable>arbitrary value</replaceable> is
ignored.</para>
<example>
<title>Delete Account Metadata HTTP Request</title>
<literallayout class="monospaced"><xi:include href="samples/account-delete-metadata-req.txt" parse="text"/></literallayout>
<para>No response body is returned. A status code from 200
to 299 indicates success.</para>
</example>
</section>
</section> </section>

6
openstack-object-storage-dev/section_object_api_tempurl.xml → openstack-object-storage-dev/section_object-api-tempurl.xml
View File

@ -14,10 +14,12 @@
xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml" xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0" xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="object-storage-tempurl"> xml:id="tempurl">
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<title>Temporary URL middleware</title> <title>Temporary URL middleware</title>
<para>A temporary URL gives users temporary access to objects. For <para>To discover whether your Object Storage system supports
this feature, see <xref linkend="discoverability"
/>. Alternatively, check with your service provider.</para><para>A temporary URL gives users temporary access to objects. For
example, a website might want to provide a link to download a example, a website might want to provide a link to download a
large object in Object Storage, but the Object Storage account large object in Object Storage, but the Object Storage account
has no public access. The website can generate a URL that has no public access. The website can generate a URL that

184
openstack-object-storage-dev/section_object-api-versioning.xml Normal file
View File

@ -0,0 +1,184 @@
<?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>