openstack-attic/object-api
Code Issues Proposed changes

Update Object Storage API Reference to point to wadl in api-site

Browse Source 
Partial-Bug: #1187119

Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce
author: diane fleming
This commit is contained in:
Diane Fleming
2013-12-31 14:05:11 -06:00
parent c9a1a597b6
commit cd98f1acd8
19 changed files with 1537 additions and 1519 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,192 +1,122 @@
<?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>
<title>General API information</title>
<para>The Object Storage API is implemented as a set of
Representational state transfer (REST) web services. You use
standard HTTP calls to perform authentication and
account-level, container-level, and object-level operations.
For more information, see <link
xlink:href="http://en.wikipedia.org/wiki/Representational_State_Transfer"
>Representational state transfer</link>.</para>
<para>Object Storage HTTP requests have the following
constraints:</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 bytes</td>
<td/>
</tr>
<tr>
<td>Length per HTTP request line</td>
<td>8192 bytes</td>
<td/>
</tr>
<tr>
<td>Length of HTTP request</td>
<td>5 GBs</td>
<td/>
</tr>
<tr>
<td>Length of container names</td>
<td>256 bytes</td>
<td>Cannot contain the <literal>/</literal>
character.</td>
</tr>
<tr>
<td>Length of object names</td>
<td>1024 bytes</td>
<td>No character restrictions.</td>
</tr>
</tbody>
</informaltable>
<para>Container and object names must be UTF-8 encoded and
properly URL-encoded before you call the API binding. If you
use an API binding that performs the URL-encoding for you, do
not URL-encode the container and object names before you call
the API binding. Otherwise, you double-encode these names.
Check the length restrictions against the URL-encoded
string.</para>
<para>Each Object Storage API request must include an
<firstterm>authentication token</firstterm> in the
<code>X-Auth-Token</code> HTTP header. Clients use an
authentication service to obtain this token and the OpenStack
Object Storage URLs. For information, see <xref
linkend="authentication-object-dev-guide"/>.</para>
<para><!--There are actually two different sets of ReST services that make up the full OpenStack Object Storage product. -->You
specify the Object Storage URL in the
<code>X-Storage-Url</code> header. This service manages
the system data. Example operations include 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>The purpose of each HTTP method depends on which service the
call is made against. For example, a &PUT; request against the
service specified in the <code>X-Storage-Url</code> header is
used to create containers and upload
objects.<!--, 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>
<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>The following sections describe the tasks that you can
perform in the storage system:</para>
<itemizedlist>
<listitem>
<para><link xlink:href="storage-account-services">Storage
account services</link>. Use to perform
account-level tasks.</para>
</listitem>
<listitem>
<para><link xlink:href="storage-container-services"
>Storage container services</link>. Use to perform
container-level tasks.</para>
</listitem>
<listitem>
<para><link xlink:href="storage-object-services">Storage
object services</link>. Use to perform
object-level tasks.</para>
</listitem>
</itemizedlist>
<xi:include href="section_authentication.xml"/>
<xi:include href="section_serialized_list_output.xml"/>
<xi:include href="section_large_lists_objects.xml"/>
</chapter>

2
openstack-object-storage-dev/ch_object-api-overview.xml
View File

@@ -53,7 +53,7 @@ format="SVG" scale="60"/>
xlink:href="http://bugs.launchpad.net/swift"
>http://bugs.launchpad.net/swift</link>.</para>
<section xml:id="intended-audience-object-dev-guide">
<title>Intended Audience</title>
<title>Intended audience</title>
<para>This guide is intended to assist software developers who
want to develop applications using the OpenStack Object
Storage API. It fully documents the ReST application

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

@@ -1,82 +1,10 @@
<?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>
xml:id="ch_object-storage-dev-api-storage" role="api-reference">
<title>API operations</title>
<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>

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

File diff suppressed because it is too large Load Diff

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>

7
openstack-object-storage-dev/samples/xml_curl.txt Normal file
View File

@@ -0,0 +1,7 @@
curl -i https://dfw.servers.api.rackspacecloud.com/v2/$account/servers.xml \
-X POST \
-H "X-Auth-Project-Id: $account" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-H "X-Auth-Token: $token" \
-T server_post_req.xml | ppxml

74
openstack-object-storage-dev/section_authentication.xml Normal file
View File

@@ -0,0 +1,74 @@
<?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-object-dev-guide">
<title>Authentication</title>
<para>The owner of an Object Storage account controls access to
that account and its containers and objects.</para>
<para>By default, you have no access to accounts, containers, or
objects. However, an account owner can grant account,
container, and object access to users through access control lists
(ACLs). For more information about ACLs, see <xref
linkend="special-metadata-acls"/>.</para>
<para>As the account owner, you can modify the account metadata
and create, modify, and delete containers and objects.</para>
<para>To identity yourself as the owner of an account, include an
authentication token in the <literal>X-Auth-Token</literal>
header in your API requests. If you omit this header or supply
an incorrect authentication token, your access is
restricted.</para>
<para>The following table describes the authentication services
that you can use:</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 name is the same
as the 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>
<para>Authentication tokens expire after a time
period that the Identity Service defines.</para><para>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>
</td>
</tr>
</tbody>
</informaltable>
</section>

203
openstack-object-storage-dev/section_curl_how_curl_works.xml Normal file
View File

@@ -0,0 +1,203 @@
<?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>How cURL commands work</title>
<para>cURL is a command-line tool that you can use to interact
with <glossterm>REST</glossterm> interfaces. cURL lets you to
transmit and receive <glossterm>HTTP</glossterm> 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 use XML requests and responses, see
<xref linkend="curl_summary_xml"/>.</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>The following command is an example cURL command that
provisions a server with an isolated network:</para>
<programlisting language="bash" role="gutter: false"><?db-font-size 60%?><prompt>$</prompt> curl https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \
-X POST \
-H "X-Auth-Project-Id: $account" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Auth-Token: $token" \
-d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07-af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid": "538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid": "11111111-1111-1111-1111-111111111111"}]}}' \
| python -m json.tool</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>
<?hard-pagebreak?>
<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>
<para>Common headers in Rackspace API requests are:<itemizedlist>
<listitem>
<para><literal>Content-Type</literal>.
Required for operations with a
request body. </para>
<para>Specifies the format of the
request body. The syntax for the
<literal>Content-Type</literal>
header is:</para>
<screen><computeroutput>Content-Type: application/<parameter>format</parameter></computeroutput></screen>
<para>Where
<parameter>format</parameter> is
either <literal>json</literal> or
<literal>xml</literal>.</para>
</listitem>
<listitem>
<para><literal>X-Auth-Project-Id</literal>.
Optional. Specifies the project ID,
which can be your account number or
another value.</para>
</listitem>
<listitem>
<para><literal>Accept</literal>.
Optional. </para>
<para>Specifies the format of the
response body. The syntax for the
<literal>Accept</literal> header
is:</para>
<screen><computeroutput>Accept: application/<parameter>format</parameter></computeroutput></screen>
<para>Where
<parameter>format</parameter> is
either <literal>json</literal> or
<literal>xml</literal>. Default is
<literal>json</literal>.</para>
</listitem>
<listitem>
<para><literal>X-Auth-Token</literal>.
Required. Specifies the
authentication token.</para>
</listitem>
</itemizedlist></para>
</td>
</tr>
<tr>
<td>
<option>-i</option>
</td>
<td>
<para>Includes the HTTP header 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 json.tool, import the json module. For
information about the json.tool, 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
simplejson module and use the simplejson.tool. For
information about the simple.json 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>
<?hard-pagebreak?>
<xi:include href="section_curl_xml.xml"/>
</section>

119
openstack-object-storage-dev/section_curl_xml.xml Normal file
View File

@@ -0,0 +1,119 @@
<?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 role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</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_summary_xml">
<title>XML requests and responses</title>
<para>The following example shows a cURL command that specifies an
XML request body and returns an XML response. The command
creates a server:</para>
<example xml:id="xml_example">
<title>cURL Command Example: XML Request and Response</title>
<programlistingco>
<areaspec>
<area xml:id="xml_curl.txt.endpoint"
units="linecolumn" coords="1 87"/>
<area xml:id="xml_curl.txt.content" units="linecolumn"
coords="4 46"/>
<area xml:id="xml_curl.txt.accept" units="linecolumn"
coords="5 40"/>
<area xml:id="xml_curl.txt.file" units="linecolumn"
coords="7 29"/>
<area xml:id="xml_curl.txt.ppxml" units="linecolumn"
coords="7 40"/>
</areaspec>
<programlisting language="bash" role="gutter: false"><?db-font-size 65%?><prompt>$</prompt> <xi:include href="samples/xml_curl.txt" parse="text"/></programlisting>
</programlistingco>
</example>
<para>The example, <xref linkend="xml_example"/>, includes the
following changes:<calloutlist>
<callout arearefs="xml_curl.txt.endpoint">
<para>Append <literal>.xml</literal> to the endpoint
in the cURL command to return an XML
response.</para>
</callout>
<callout arearefs="xml_curl.txt.content">
<para>The <literal>Content-Type:</literal> header
specifies <literal>application/xml</literal>
instead of <literal>application/json</literal>.
</para>
</callout>
<callout arearefs="xml_curl.txt.accept">
<para>The <literal>Accept:</literal> header specifies
<literal>application/xml</literal> instead of
<literal>application/json</literal>. </para>
</callout>
<callout arearefs="xml_curl.txt.file">
<para>If the request requires a request body, specify
it in XML format. In this example, the XML body is
passed in the
<filename>server_post_req.xml</filename>
file.</para>
</callout>
<callout arearefs="xml_curl.txt.ppxml">
<para>To pretty-print the XML output, set the <literal
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"
>ppxml</literal> alias, as follows: </para>
<programlisting language="bash" role="gutter: false"><?db-font-size 50%?><prompt>$</prompt> alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"'</programlisting>
<para 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">Then,
append the <literal>ppxml</literal> alias to your
cURL command.</para>
</callout>
</calloutlist></para>
<para>The following example shows the contents of the
<filename>server_post_req.xml</filename> file:</para>
<programlisting language="xml"><?db-font-size 55%?><xi:include href="samples/server-post-req.xml" parse="text"/></programlisting>
<?hard-pagebreak?>
<para><emphasis role="bold">Output:</emphasis> The cURL command
returns information about the new server in XML format, as
shown in the following example:</para>
<programlisting language="xml"><?db-font-size 65%?><xi:include href="samples/server-post-resp.xml" parse="text"/></programlisting>
</section>

203
openstack-object-storage-dev/section_gs_curl_how_curl_works.xml Normal file
View File

@@ -0,0 +1,203 @@
<?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>How cURL Commands Work</title>
<para>cURL is a command-line tool that you can use to interact
with <glossterm>REST</glossterm> interfaces. cURL lets you to
transmit and receive <glossterm>HTTP</glossterm> 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 use XML requests and responses, see
<xref linkend="curl_summary_xml"/>.</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>The following command is an example cURL command that
provisions a server with an isolated network:</para>
<programlisting language="bash" role="gutter: false"><?db-font-size 60%?><prompt>$</prompt> curl https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \
-X POST \
-H "X-Auth-Project-Id: $account" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Auth-Token: $token" \
-d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07-af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid": "538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid": "11111111-1111-1111-1111-111111111111"}]}}' \
| python -m json.tool</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>
<?hard-pagebreak?>
<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>
<para>Common headers in Rackspace API requests are:<itemizedlist>
<listitem>
<para><literal>Content-Type</literal>.
Required for operations with a
request body. </para>
<para>Specifies the format of the
request body. The syntax for the
<literal>Content-Type</literal>
header is:</para>
<screen><computeroutput>Content-Type: application/<parameter>format</parameter></computeroutput></screen>
<para>Where
<parameter>format</parameter> is
either <literal>json</literal> or
<literal>xml</literal>.</para>
</listitem>
<listitem>
<para><literal>X-Auth-Project-Id</literal>.
Optional. Specifies the project ID,
which can be your account number or
another value.</para>
</listitem>
<listitem>
<para><literal>Accept</literal>.
Optional. </para>
<para>Specifies the format of the
response body. The syntax for the
<literal>Accept</literal> header
is:</para>
<screen><computeroutput>Accept: application/<parameter>format</parameter></computeroutput></screen>
<para>Where
<parameter>format</parameter> is
either <literal>json</literal> or
<literal>xml</literal>. Default is
<literal>json</literal>.</para>
</listitem>
<listitem>
<para><literal>X-Auth-Token</literal>.
Required. Specifies the
authentication token.</para>
</listitem>
</itemizedlist></para>
</td>
</tr>
<tr>
<td>
<option>-i</option>
</td>
<td>
<para>Includes the HTTP header 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 json.tool, import the json module. For
information about the json.tool, 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
simplejson module and use the simplejson.tool. For
information about the simple.json 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>
<?hard-pagebreak?>
<xi:include href="section_gs_curl_xml.xml"/>
</section>

122
openstack-object-storage-dev/section_gs_curl_xml.xml Normal file
View File

@@ -0,0 +1,122 @@
<?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 role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</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_summary_xml">
<title>XML Requests and Responses</title>
<para>The following example shows a cURL command that specifies an
XML request body and returns an XML response. The command
creates a server:</para>
<example xml:id="xml_example">
<title>cURL Command Example: XML Request and Response</title>
<programlistingco>
<areaspec>
<area xml:id="xml_curl.txt.endpoint"
units="linecolumn" coords="1 87"/>
<area xml:id="xml_curl.txt.content" units="linecolumn"
coords="4 46"/>
<area xml:id="xml_curl.txt.accept" units="linecolumn"
coords="5 40"/>
<area xml:id="xml_curl.txt.file" units="linecolumn"
coords="7 29"/>
<area xml:id="xml_curl.txt.ppxml" units="linecolumn"
coords="7 40"/>
</areaspec>
<programlisting language="bash" role="gutter: false"><?db-font-size 65%?><prompt>$</prompt> <xi:include href="../samples/xml_curl.txt" parse="text"/></programlisting>
</programlistingco>
</example>
<para>The example, <xref linkend="xml_example"/>, includes the
following changes:<calloutlist>
<callout arearefs="xml_curl.txt.endpoint">
<para>Append <literal>.xml</literal> to the endpoint
in the cURL command to return an XML
response.</para>
</callout>
<callout arearefs="xml_curl.txt.content">
<para>The <literal>Content-Type:</literal> header
specifies <literal>application/xml</literal>
instead of <literal>application/json</literal>.
</para>
</callout>
<callout arearefs="xml_curl.txt.accept">
<para>The <literal>Accept:</literal> header specifies
<literal>application/xml</literal> instead of
<literal>application/json</literal>. </para>
</callout>
<callout arearefs="xml_curl.txt.file">
<para>If the request requires a request body, specify
it in XML format. In this example, the XML body is
passed in the
<filename>server_post_req.xml</filename>
file.</para>
</callout>
<callout arearefs="xml_curl.txt.ppxml">
<para>To pretty-print the XML output, set the <literal
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"
>ppxml</literal> alias, as follows: </para>
<programlisting language="bash" role="gutter: false"><?db-font-size 50%?><prompt>$</prompt> alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"'</programlisting>
<para 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">Then,
append the <literal>ppxml</literal> alias to your
cURL command. </para>
</callout>
</calloutlist></para>
<para>The following example shows the contents of the
<filename>server_post_req.xml</filename> file:</para>
<programlisting language="xml"><?db-font-size 55%?><xi:include href="../samples/server-post-req.xml" parse="text"/></programlisting>
<?hard-pagebreak?>
<para><emphasis role="bold">Output:</emphasis> The cURL command
returns information about the new server in XML format, as
shown in the following example:</para>
<programlisting language="xml"><?db-font-size 65%?><xi:include href="../samples/server-post-resp.xml" parse="text"/></programlisting>
</section>

46
openstack-object-storage-dev/section_large_lists_objects.xml Normal file
View File

@@ -0,0 +1,46 @@
<?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="list-large-number-of-objects">
<title>Control a large list of objects</title>
<para>The system returns a maximum of 10,000 container names for
each request. To get subsequent container names, you must make
another request 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 names
again. Note that the marker value should be URL-encoded before
you send the HTTP request.</para>
<para>If 10,000 is more than desired, use the limit parameter. If
the number of container names returned equals the specified
limit, or 10,000 if no limit is specified, you can assume
there are more container names.</para>
<para>For example, for a list of five container names, if you
specify a limit of two, two items are returned. You can assume
there are more container names to list, so make another
request with a marker of the last item returned.</para>
<example>
<title>List large number of objects</title>
<para>For example, use a listing of five object names:</para>
<literallayout class="monospaced">gala
grannysmith
honeycrisp
jonagold
reddelicious</literallayout>
<para>Use a limit of two:</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, two items are returned, and there might be
more.</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-marker2-req.txt" parse="text"/></literallayout>
<para>You now receive a one-item response, which is fewer than
the limit number of container names. This indicates that
this is the end of the list. By using
<code>end_marker</code>, you can limit the result set
to container names less than the specified value.</para>
<literallayout class="monospaced"><xi:include href="samples/objects-list-end-marker-req.txt" parse="text"/></literallayout>
</example>
</section>

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

@@ -31,7 +31,7 @@ format="SVG" scale="60"/>
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="Create_Static_Website-dle4000">
<title>Create Static Website</title>
<title>Create static website</title>
<para>You can use your swift account to create a static website.
This mode is normally only active for anonymous requests. To
use it with authenticated requests, set the header
@@ -100,9 +100,10 @@ format="SVG" scale="60"/>
<para>You can create and set custom error pages for visitors
to your website; currently, only 401 (Unauthorized) and
404 (Not Found) errors are supported. To do this, set the
metadata header, <code>X-Container-Meta-Web-Error</code>.</para>
metadata header,
<code>X-Container-Meta-Web-Error</code>.</para>
<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
<code>X-Container-Meta-Web-Error</code> to
<code>error.html</code>, 401 errors will display the

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:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="doc_history">
<title>Document Change History</title>
<title>Document change history</title>
<para>This version of the document replaces and obsoletes
all previous versions. The following table describes the latest changes:</para>
<?rax revhistory?>

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

@@ -31,8 +31,21 @@ format="SVG" scale="60"/>
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="storage-container-services">
<title>Storage Container Services</title>
<para>You can perform the following operations for
<title>Storage container services</title>
<para>Lists objects, creates and delete containers, and gets, creates, updates, or deletes 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="#listObjects"/>
<wadl:method href="#createcontainer"/>
<wadl:method href="#deletecontainer"/>
<wadl:method href="#retrievecontainermeta"/>
<wadl:method href="#updateacontainermeta"/>
<wadl:method href="#deletecontainermeta"/>
</wadl:resource>
</wadl:resources>
<!-- <para>You can perform the following operations for
containers:</para>
<informaltable rules="all">
<thead>
@@ -191,172 +204,7 @@ format="SVG" scale="60"/>
<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>
@@ -489,11 +337,11 @@ photos/animals/dogs/terrier.jpg</literallayout>
<example>
<title>View Container Metadata HTTP Response</title>
<literallayout class="monospaced"><xi:include href="samples/container-view-metadata-resp.txt" parse="text"/></literallayout>
</example>
</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>
<section xml:id="delete-container-metadata">
<title>Delete Container Metadata</title>
<para>To delete a metadata header send an empty value for that
@@ -514,5 +362,5 @@ photos/animals/dogs/terrier.jpg</literallayout>
<para>No response body is returned. A status code of 2xx
(between 200 and 299, inclusive) indicates success.</para>
</example>
</section>
</section>-->
</section>

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

@@ -16,7 +16,9 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="storage-object-services">
<title>Storage Object Services</title>
<title>Storage object services</title>
<para>Creates, updates, gets details for, and deletes objects.
Gets and updates object metadata.</para>
<para>An object represents the data and metadata for the files
stored in the system. Through the ReST interface, you can
include metadata for an object by adding custom HTTP headers
@@ -27,7 +29,19 @@
Then, you can download the segments as a single concatenated
object. You can use HTTP requests to work with the segments
and manifests directly.</para>
<informaltable rules="all">
<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="#listObjects"/>
<wadl:method href="#retrieveobject"/>
<wadl:method href="#createobject"/>
<wadl:method href="#deleteobject"/>
<wadl:method href="#copyobject"/>
<wadl:method href="#retrieveobjectmeta"/>
<wadl:method href="#updateaobjmeta"/>
</wadl:resource>
</wadl:resources>
<!-- <informaltable rules="all">
<thead>
<tr>
<td colspan="1">Verb</td>
@@ -205,7 +219,7 @@
</tbody>
</informaltable>
<example>
<title>Get Object Details HTTP Request</title>
<title>Get Object Details request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-req.txt" parse="text"/></literallayout>
</example>
<para>The object data is returned in the response body. Object
@@ -214,27 +228,27 @@
inclusive) indicates success; status 404 (Not Found) is
returned if no such object exists.</para>
<example>
<title>Get Object Details HTTP Response</title>
<title>Get Object Details response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-resp.txt" parse="text"/></literallayout>
</example>
<para>These examples include an object that contains 10 bytes
of data: <literal>0123456789</literal>.</para>
<example>
<title>Get Object Details HTTP Request Using Range</title>
<title>Get Object Details request: HTTP Using Range</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-range-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get Object Details HTTP Response When Using
<title>Get Object Details response: HTTP When Using
Range</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-range-resp.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get Object Details HTTP Request Using Multiple
<title>Get Object Details request: HTTP Using Multiple
Ranges</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-ranges-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get Object Details HTTP Response When Using
<title>Get Object Details response: HTTP When Using
Multiple Ranges</title>
<literallayout class="monospaced"><xi:include href="samples/object-get-ranges-resp.txt" parse="text"/></literallayout>
</example>
@@ -256,7 +270,7 @@
object at the specified time and shortly after the
expiration date, it removes the object from the storage
system.</para>
<para>The HTTP response will include the MD5 checksum of the
<para>The response: HTTP will include the MD5 checksum of the
data written to the storage system. If you do not send the
ETag in the request, you should compare the value returned
with your content's MD5 locally to perform the end-to-end
@@ -273,7 +287,7 @@
<literal>allowed_headers</literal> option in the
object-server configuration.</para>
<example>
<title>Create or Update Object HTTP Request</title>
<title>Create or Update Object request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-create-req.txt" parse="text"/></literallayout>
<literallayout class="monospaced">[ ... ]</literallayout>
</example>
@@ -285,7 +299,7 @@
does NOT match the (optionally) supplied ETag value, a 422
(Unprocessable Entity) response is returned.</para>
<example>
<title>Create or Update Object HTTP Response</title>
<title>Create or Update Object response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-create-resp.txt" parse="text"/></literallayout>
</example>
<section xml:id="chunked-transfer-encoding">
@@ -308,8 +322,7 @@
you have files that are larger than 5GB see <xref
linkend="large-object-creation"/>.</para>
<example>
<title>Upload Unspecified Quantity of Content HTTP
Request</title>
<title>Upload Unspecified Quantity of Contentrequest: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/chunked-transfer-encoding-req.txt" parse="text"/></literallayout>
</example>
<example>
@@ -318,9 +331,9 @@
<literallayout class="monospaced"><xi:include href="samples/chunked-transfer-encoding-resp.txt" parse="text"/></literallayout>
</example>
</section>
</section>
</section>-->
<section xml:id="large-object-creation">
<title>Create Large Objects</title>
<title>Create large objects</title>
<para>The content of an object cannot be larger than 5GB (by
default). However, you can store larger content using two
types of objects:</para>
@@ -338,7 +351,7 @@
<para>Segment objects do not have any special features and can
be created, updated, downloaded and deleted as described
elsewhere in this document. However, a manifest object is
special -- when you download, the system concatenates the
special. When you download, the system concatenates the
contents of the segment objects and returns this in the
response body of the request. This behavior extends to the
response headers returned by &GET; and &HEAD; operations.
@@ -378,13 +391,13 @@
behavior, there are differences as explained in the
following table.</para>
<table rules="all">
<caption>Comparison of Static and Dynamic Large
Objects</caption>
<caption>Comparison of static and dynamic large
objects</caption>
<thead>
<tr>
<th>Feature</th>
<th>Static Large Object</th>
<th>Dynamic Large Object</th>
<th>Static large object</th>
<th>Dynamic large object</th>
</tr>
</thead>
<tbody>
@@ -423,8 +436,8 @@
completely new manifest object of the same
name with a different manifest list.</td>
<td>You can upload new segment objects or remove
existing segments --- the names must simply
match the <code>&lt;prefix></code> supplied in
existing segments. The names must simply match
the <code>&lt;prefix></code> supplied in
<code>X-Object-Manifest</code>.</td>
</tr>
<tr>
@@ -480,7 +493,7 @@
</tbody>
</table>
<section xml:id="dynamic-large-object-creation">
<title>Dynamic Large Objects</title>
<title>Dynamic large objects</title>
<para>Objects that are larger than 5GB must be segmented,
prior to upload. You then upload the segments like you
would any other object and create a dynamic large
@@ -513,13 +526,13 @@
manifest will still be available to download the first
set of segments.</para>
<example>
<title>Upload Segment of Large Object HTTP
Request</title>
<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 HTTP
Response</title>
<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 2xx
@@ -534,13 +547,13 @@
<para>You can continue uploading segments like this
example shows, prior to uploading the manifest.</para>
<example>
<title>Upload Next Segment of Large Object HTTP
Request</title>
<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 HTTP
Response</title>
<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
@@ -551,11 +564,11 @@
manifest file for subsequent additional
segments.</para>
<example>
<title>Upload Manifest HTTP Request</title>
<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 HTTP Response</title>
<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 Content-Type for a &GET; or &HEAD; on
@@ -565,10 +578,11 @@
&PUT; request.</para>
</section>
<section xml:id="static-large-objects">
<title>Static Large Objects</title>
<para>To create a static large object:</para>
<orderedlist>
<listitem>
<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 <code>ETag</code>
@@ -579,8 +593,8 @@
<code>ETag</code> request header. This
ensures that the upload cannot corrupt your
data.</para>
</listitem>
<listitem>
</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
@@ -588,8 +602,8 @@
<code>?multipart-manifest=put</code> query
string at the end of the manifest object
name.</para>
</listitem>
</orderedlist>
</step>
</procedure>
<para>The body of the &PUT; request on the manifest object
comprises a json list, where each element contains the
following:</para>
@@ -613,7 +627,7 @@
</listitem>
</itemizedlist>
<example>
<title>Static Large Object Manifest List</title>
<title>Static large object manifest list</title>
<para>This is an example containing three segment
objects. In this example, you can use several
containers and the object names do not have to
@@ -622,17 +636,16 @@
<literallayout class="monospaced"><xi:include href="samples/slo-manifest-example.txt" parse="text"/></literallayout>
</example>
<para>The <code>Content-Length</code> request header must
contain the length of the json content -- not the
length of the segment objects. However, after the
&PUT; operation completes, the
<code>Content-Length</code> metadata is set to the
total length of all the object segments. A similar
situation applies to the <code>ETag</code>. If used in
the &PUT; operation, it must contain the MD5 checksum
of the json content. The <code>ETag</code> metadata
value is then set to be the MD5 checksum of the
concatenated <code>ETag</code> values of the object
segments. You may also set the
contain the length of the json content. Not the length
of the segment objects. However, after the &PUT;
operation completes, the <code>Content-Length</code>
metadata is set to the total length of all the object
segments. A similar situation applies to the
<code>ETag</code>. If used in the &PUT; operation,
it must contain the MD5 checksum of the json content.
The <code>ETag</code> metadata value is then set to be
the MD5 checksum of the concatenated <code>ETag</code>
values of the object segments. You may also set the
<code>Content-Type</code> request header and
custom object metadata.</para>
<para>When the &PUT; operation sees the
@@ -654,7 +667,7 @@
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
object, the manifest object is deleted. The segment
objects are not affected. However, if you add the
query parameter
<code>?multipart-manifest=delete</code>, the
@@ -669,7 +682,7 @@
</section>
</section>
<section xml:id="assigning-cors-headers-to-requests">
<title>Assigning CORS Headers to Requests</title>
<title>Assign CORS headers to requests</title>
<para>CORS is a specification that stands for Cross-Origin
Resource Sharing. It defines how browsers and servers
communicate across origins using HTTP headers, such as
@@ -706,7 +719,7 @@
</itemizedlist></para>
<para>You can assign these headers to objects only.</para>
<example>
<title>Assign CORS Header HTTP Request</title>
<title>Assign CORS header request: HTTP</title>
<para>In the example, the origin header is assigned that
indicates where the file came from. This allows you to
provide security that requests to your Object Storage
@@ -717,13 +730,13 @@
</section>
<section
xml:id="enabling-file-compression-with-content-encoding-header">
<title>Enabling File Compression with the Content-Encoding
Header</title>
<para>The Content-Encoding header allows a file to be
<title>Enable file compression with the Content-Encoding
header</title>
<para>The Content-Encoding header enables a file to be
compressed without losing the identity of the underlying
media type of the file, for example, a video.</para>
<example>
<title>Content-Encoding Header HTTP Request</title>
<title>Content-Encoding header request: HTTP</title>
<para>In the example, the content-encoding header is
assigned with an attachment type that indicates how
the file should be downloaded:</para>
@@ -732,14 +745,14 @@
</section>
<section
xml:id="enabling-browser-bypass-with-content-disposition-header">
<title>Enabling Browser Bypass with the Content-Disposition
Header</title>
<title>Enable browser bypass with the Content-Disposition
header</title>
<para>When an object is assigned the Content-Disposition
header you can override a browser's default behavior for a
file so that the download program saves the file rather
than displaying it using default browser settings.</para>
<example>
<title>Content-Disposition Header HTTP Request</title>
<title>Content-Disposition header request: HTTP</title>
<para>In the example, the content-encoding header is
assigned with an attachment type that indicates how
the file should be downloaded.</para>
@@ -747,8 +760,8 @@
</example>
</section>
<section xml:id="Expiring_Objects-e1e3228">
<title>Expiring Objects with the X-Delete-After and
X-Delete-At Headers</title>
<title>Expire objects with the X-Delete-After and X-Delete-At
headers</title>
<para>When an object is assigned either an
<code>X-Delete-After</code> or
<code>X-Delete-At</code> header when doing a &PUT; or
@@ -759,11 +772,10 @@
be outdated at a future time.</para>
<para>The <code>X-Delete-At</code> header requires a Unix
Epoch timestamp, in integer form; for example: 1348691905
represents Wed, 26 Sep 2012 20:38:25 GMT.
<!-- Exchanged POSIX in / favor of Epoch for the / sake of clarity dsh 02-06-12 -->By
setting the header to a specific Epoch time, you indicate
when you want the object to expire, not be served, and be
deleted completely from the storage system.</para>
represents Wed, 26 Sep 2012 20:38:25 GMT. setting the
header to a specific Epoch time, you indicate when you
want the object to expire, not be served, and be deleted
completely from the storage system.</para>
<para>The <code>X-Delete-After</code> header takes an integer
number of seconds and calculates the amount of time from
now that you want the object to be deleted. The proxy
@@ -774,7 +786,7 @@
<para>For existing objects that you want to assign expiration
headers to, use the &POST; operation.</para>
<example>
<title>Delete Object at HTTP Request</title>
<title>Delete object at request: HTTP</title>
<para>In the example, the <code>X-Delete-At</code> header
is assigned with a Unix Epoch timestamp in integer
form for Mon, 11 Jun 2012 15:38:25 GMT. Use <link
@@ -784,19 +796,16 @@
<literallayout class="monospaced"><xi:include href="samples/object-delete-at-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Delete Object after HTTP Request</title>
<para><!-- Reworded this here / paragraph to make more sense / and match what I see dsh 02-06-12 -->In
this example, the <code>X-Delete-After</code> header
is assigned a value in seconds, equivalent to 10 days.
After this time, the object expires.</para>
<!-- Removed, "The system then converts the time necessary for an <code>X-Delete-At</code> header operation." Doesn't seem to match dsh 02-06-12-->
<title>Delete object after request: HTTP</title>
<para>In this example, the <code>X-Delete-After</code>
header is assigned a value in seconds, 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>
</example>
</section>
<section xml:id="Object_Versioning-e1e3230">
<!-- begin 4.3.2.7 -->
<title>Object Versioning</title>
<title>Object versioning</title>
<para>Object versioning allows you to store multiple versions
of your content to recover from unintended overwrites. It
provides an easy method to implement version control which
@@ -869,7 +878,7 @@
container, remove its <code>X-Versions-Location</code>
metadata by sending an empty key value.</para>
<example>
<title>Object Versioning with cURL</title>
<title>Object versioning with cURL</title>
<para>Make sure a version-storing container exists,
creating it if necessary (this example names it
"versions"). Then create a container with the
@@ -904,7 +913,7 @@
http://&lt;storage_url&gt;/versions?prefix=008myobject/</userinput></screen>
</example>
</section>
<section xml:id="copy-object">
<!-- <section xml:id="copy-object">
<title>Copy Object</title>
<para>Suppose you upload a file with the wrong object name or
content type, or you needed to move some objects to
@@ -990,7 +999,7 @@
time. Refer to <link linkend="Expiring_Objects-e1e3228"
>Expiring Objects</link> for more details.</para>
<example>
<title>Object Delete HTTP Request</title>
<title>Object Delete request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-delete-req.txt" parse="text"/></literallayout>
</example>
<para>No response body is returned. A status code of 2xx (
@@ -998,7 +1007,7 @@
code 404 (Not Found) is returned when the object does not
exist.</para>
<example>
<title>Object Delete HTTP Response</title>
<title>Object Delete response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-delete-resp.txt" parse="text"/></literallayout>
</example>
</section>
@@ -1009,7 +1018,7 @@
<para>The only required header to be sent in the request is
the authorization token.</para>
<example>
<title>Get Object Metadata HTTP Request</title>
<title>Get Object Metadata request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>No response body is returned. Metadata is returned as
@@ -1017,7 +1026,7 @@
inclusive) indicates success; status 404 (Not Found) is
returned when the object does not exist.</para>
<example>
<title>Get Object Metadata HTTP Response</title>
<title>Get Object Metadata response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
@@ -1040,7 +1049,7 @@
delete all existing metadata added with a previous
&PUT;/&POST;.</para>
<example>
<title>Update Object Metadata HTTP Request</title>
<title>Update Object Metadata request: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-update-metadata-req.txt" parse="text"/></literallayout>
</example>
<para>No response body is returned. A status code of 2xx
@@ -1048,8 +1057,8 @@
404 (Not Found) is returned if the requested object does
not exist.</para>
<example>
<title>Update Object Metadata HTTP Response</title>
<title>Update Object Metadata response: HTTP</title>
<literallayout class="monospaced"><xi:include href="samples/object-update-metadata-resp.txt" parse="text"/></literallayout>
</example>
</section>
</section>-->
</section>

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"?>
<!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"
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">
<title>Storage Account Services</title>
<para>Perform the following operations at the account level of the
URL:</para>
<informaltable rules="all">
<thead>
<tr>
<td colspan="1">Verb</td>
<td colspan="2">URI</td>
<td colspan="3">Description</td>
</tr>
</thead>
<tbody>
<tr>
<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>
<title>Storage account services</title>
<para>Lists containers and gets, creates, updates, or deletes
account metadata. You can perform these actions at the account
level of the storage system.</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="#listContainers"/>
<wadl:method href="#retrieveaccountmeta"/>
<wadl:method href="#updateaccountmeta"/>
<wadl:method href="#deleteaccountmeta"/>
</wadl:resource>
</wadl:resources>
</section>

32
openstack-object-storage-dev/section_serialized_list_output.xml Normal file
View File

@@ -0,0 +1,32 @@
<?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="serialized-list-output">
<title>Serialized list output</title>
<para>If you append the <code>format=xml</code> or
<code>format=json</code> argument to the storage
account URL, the service serves extended container
information serialized in the specified format. The sample
responses are formatted for readability. The following
example HTTP request asks for a JSON response, so the
response returns an HTTP header and a JSON
response.</para>
<example>
<title>Get object details request: HTTP and JSON</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-json-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get object details response: HTTP and JSON</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>Get object details request: XML</title>
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-xml-req.txt" parse="text"/></literallayout>
</example>
<example>
<title>Get object 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>