openstack-attic
/
object-api
Code Issues Proposed changes

Merge "Update Object Storage API Reference"

changes/69/75569/1
Jenkins 2014-02-16 22:06:20 +00:00 committed by Gerrit Code Review
parent 389b4065b8 ed4f3c4db9
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
target/
publish-docs/
/build-*.log.gz
# NetBeans user-specific build actions
nbactions.xml
# Ignore Vagrant Related Files
acceptance_config.yml
boxes/*
/.vagrant
# Testenvironment
.tox
.tox/
# Editors
*~
.*.swp
.bak
# NetBeans user-specific build actions
nbactions.xml

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

@ -1,30 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!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 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>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
@ -67,13 +43,24 @@
Application Programming Interface (API) v1.</para>
</abstract>
<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>
<date>2014-01-24</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Added information about form &POST; and
temporary URL middleware.</para>
<para>Added information about form &POST; and temporary
URL middleware.</para>
</listitem>
</itemizedlist>
</revdescription>
@ -159,7 +146,7 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Fixed bugs 890435 and 907563 - Add/Update
<para>Fixed bugs 890435 and 907563; Add/Update
Container Metadata and Expiring Objects. Changed to
Maven 1.0.10.</para>
</listitem>
@ -196,9 +183,9 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Removed references to ACL (Access Control List).
Fixed error in examples referring to X-Auth-Key where
it should be X-Auth-Token. Added section
<para>Removed references to Access Control List (ACL).
Fixed error in examples referring to <literal>X-Auth-Key</literal> where
it should be <literal>X-Auth-Token</literal>. Added section
numbers.</para>
</listitem>
</itemizedlist>
@ -210,7 +197,7 @@
<itemizedlist spacing="compact">
<listitem>
<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>
</listitem>
</itemizedlist>
@ -221,7 +208,7 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Initial Release.</para>
<para>Initial release.</para>
</listitem>
</itemizedlist>
</revdescription>
@ -230,7 +217,7 @@
</info>
<!-- 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="ch_object-api-general.xml"/>
<xi:include href="ch_object-api-storage-services.xml"/>
<xi:include href="ch_object-api-troubleshooting-examples.xml"/>
<xi:include href="ch_object-api-concepts-and-features.xml"/>
<xi:include href="ch_object-api-operations.xml"/>
<xi:include href="ch_object-api-examples.xml"/>
</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