Initial move of OpenStack Object Storage API guide to github repo
Change-Id: I90fe30c6d542f02bc12fd7d651cc70828363a355
This commit is contained in:
Anne Gentle
parent
b8d430c029
commit
ac49d00862
|
|
@ -0,0 +1,2 @@
|
|||
.DS_Store?
|
||||
target/
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
This repository contains the RESTful API information for the OpenStack Object Storage Service, also known as Swift. The Swift project provides services for object storage and retrieval as well as assigning metadata.
|
||||
|
||||
Contributing
|
||||
============
|
||||
Our community welcomes all people interested in open source cloud computing, and there are no formal membership requirements. The best way to join the community is to talk with others online or at a meetup and offer contributions through Launchpad, the OpenStack wiki, or blogs. We welcome all types of contributions, from blueprint designs to documentation to testing to deployment scripts.
|
||||
|
||||
Installing
|
||||
==========
|
||||
Refer to http://swift.openstack.org to learn more about installing an OpenStack Object Storage server that can respond to these API commands.
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<groupId>org.openstack.docs</groupId>
|
||||
<artifactId>openstack-object-api-guide</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<packaging>jar</packaging>
|
||||
<name>OpenStack Guides</name>
|
||||
<!-- ################################################ -->
|
||||
<!-- USE "mvn clean generate-sources" to run this POM -->
|
||||
<!-- ################################################ -->
|
||||
<profiles>
|
||||
<profile>
|
||||
<id>Rackspace Research Repositories</id>
|
||||
<activation>
|
||||
<activeByDefault>true</activeByDefault>
|
||||
</activation>
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
</profile>
|
||||
</profiles>
|
||||
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>target/docbkx/pdf</directory>
|
||||
<excludes>
|
||||
<exclude>**/*.fo</exclude>
|
||||
</excludes>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
|
||||
<plugin>
|
||||
<groupId>com.rackspace.cloud.api</groupId>
|
||||
<artifactId>clouddocs-maven-plugin</artifactId>
|
||||
<version>1.0.5-SNAPSHOT</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>goal1</id>
|
||||
<goals>
|
||||
<goal>generate-pdf</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<highlightSource>false</highlightSource>
|
||||
</configuration>
|
||||
</execution>
|
||||
<execution>
|
||||
<id>goal2</id>
|
||||
<goals>
|
||||
<goal>generate-webhelp</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<!-- These parameters only apply to webhelp -->
|
||||
<enableDisqus>0</enableDisqus>
|
||||
<disqusShortname>openstackdocs</disqusShortname>
|
||||
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
|
||||
<generateToc>
|
||||
appendix toc,title
|
||||
article/appendix nop
|
||||
article toc,title
|
||||
book title,figure,table,example,equation
|
||||
chapter toc,title
|
||||
part toc,title
|
||||
preface toc,title
|
||||
qandadiv toc
|
||||
qandaset toc
|
||||
reference toc,title
|
||||
set toc,title
|
||||
</generateToc>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
<postProcess>
|
||||
<!-- Copies the figures to the correct location for webhelp -->
|
||||
<!-- No figures in this book -->
|
||||
|
||||
<!-- Copies HTML to a release folder --> <copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/developer">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/os-objectstorage-devguide">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/os-objectstorage-devguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/developer/os-objectstorage-devguide-trunk.pdf"/>
|
||||
|
||||
<delete
|
||||
dir="${basedir}/target/docbkx/webhelp/os-objectstorage-devguide"/>
|
||||
</postProcess>
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<!-- These parameters apply to pdf and webhelp -->
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>src/docbkx</sourceDirectory>
|
||||
<includes>
|
||||
os-objectstorage-devguide.xml
|
||||
</includes>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
<branding>openstack</branding>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
|
|
@ -0,0 +1,261 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- 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="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>
|
||||
|
||||
<para>API Operations Reference Summary</para>
|
||||
<para> Storage Accounts </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">List containers</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1"><code>HEAD</code></td>
|
||||
<td colspan="2"><parameter>account</parameter></td>
|
||||
<td colspan="3">Retrieve account metadata</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<para> Storage Containers </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>/<parameter>container</parameter></td>
|
||||
<td colspan="3">List objects</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&PUT;</td>
|
||||
<td colspan="2">/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Create container</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&DELETE;</td>
|
||||
<td colspan="2">/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Delete container</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1"><code>HEAD</code></td>
|
||||
<td colspan="2">/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Retrieve container metadata</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<para> Storage Objects </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>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Retrieve object</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&PUT;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Create/Update Object</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&PUT;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Chunked transfer encoding</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&DELETE;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Delete container</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1"><code>HEAD</code></td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Retrieve object metadata</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&POST;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter>/<parameter>object</parameter></td>
|
||||
<td colspan="3">Update object metadata</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<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> Obtain your API access key from authentication service you chose when
|
||||
installing. You have some options for auth, including tempauth, which is included, or swauth, an auth service for Swift as WSGI middleware that uses Swift itself as a backing store that is provided via download from Github, or 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 Request </title>
|
||||
<literallayout class="monospaced">
|
||||
GET /v1.0 HTTP/1.1
|
||||
Host: auth.api.yourcloud.com
|
||||
X-Auth-User: jdoe
|
||||
X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89
|
||||
</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 Response</title>
|
||||
<literallayout class="monospaced">
|
||||
HTTP/1.1 204 No Content
|
||||
Date: Mon, 12 Nov 2010 15:32:21 GMT
|
||||
Server: Apache
|
||||
X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_34
|
||||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||||
Content-Length: 0
|
||||
Content-Type: text/plain; charset=UTF-8
|
||||
</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">Wikipedia
|
||||
article</link> for more information about ReST.</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 should be properly URL-encoded prior to interacting with the
|
||||
ReST interface (the language APIs handle URL encoding/decoding) and the container
|
||||
and object names must be UTF-8 encoded. 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 URIs, 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>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,185 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- 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="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-overview">
|
||||
|
||||
<title>Overview</title>
|
||||
<para>OpenStack Object Storage is an affordable, redundant, scalable, and dynamic storage
|
||||
service offering. The core storage system is designed to provide a safe, secure,
|
||||
automatically re-sizing and network accessible way to store data. You can store an
|
||||
unlimited quantity of files and each file can be as large as 5 gigabytes, plus with
|
||||
large storage support you can download and .</para>
|
||||
<para>OpenStack Object Storage allows users to store and retrieve files and content via a simple
|
||||
Web Service (ReST: Representational State Transfer) interface. There are also
|
||||
language-specific APIs that utilize the ReSTful API but make it much easier for
|
||||
developers to integrate into their applications.</para>
|
||||
<para>For more details on the OpenStack Object Storage service, please refer to <link
|
||||
xlink:href="http://swift.openstack.org"
|
||||
>http://swift.openstack.org</link>
|
||||
</para>
|
||||
<para> We welcome feedback, comments, and bug reports at <link
|
||||
xlink:href="http://bugs.launchpad.net/swift">bugs.launchpad.net/swift</link>.
|
||||
</para>
|
||||
<section xml:id="intended-audience-object-dev-guide">
|
||||
<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 programming
|
||||
interface (API) that allows developers to interact with the storage components of
|
||||
the OpenStack Object Storage system. To use the information provided here, you should first have a
|
||||
general understanding of the OpenStack Object Storage service and have access to an installation of
|
||||
OpenStack Object Storage. You should also be familiar with: </para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>ReSTful web services</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>HTTP/1.1</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>Rackspace also provides Rackspace-supported, language-specific APIs in several popular
|
||||
programming languages. Currently, the supported APIs are C#/.NET, Java, PHP, Python,
|
||||
and Ruby. These APIs utilize the ReST API and are provided to help developers
|
||||
rapidly integrate OpenStack Object Storage support into their applications without
|
||||
needing to write at the ReST interface. Each API includes its own documentation in
|
||||
its native format. For example, the Java API includes JavaDocs and the C#/.NET API
|
||||
includes a CHM file.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="doc-change-history-object-dev-guide">
|
||||
<title>Document Change History</title>
|
||||
<para>This version of the Developer Guide was forked from the Rackspace Cloud Files Developer
|
||||
Guide. The most recent changes for both guides are described in the table
|
||||
below:</para>
|
||||
<informaltable rules='all'>
|
||||
<thead>
|
||||
<tr>
|
||||
<td align="center" colspan="1">Revision Date</td>
|
||||
<td align="center" colspan="4">Summary of Changes</td>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="1" align="center">Feb. 10, 2011</td>
|
||||
|
||||
<td colspan="4">
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>
|
||||
Revised to change first to last in the first range example for fetching a portion of an object.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1" align="center">Jan. 25, 2011</td>
|
||||
|
||||
<td colspan="4">
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>
|
||||
Revised for OpenStack Object Storage use by removing CDN references, Rackspace Cloud references, and revised account examples and URLs for generic implementations.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
It's not a changed requirement that Container and Object names are required to be UTF-8, but it's pointed out in the documentation.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr><tr>
|
||||
<td colspan="1" align="center">Jan. 12, 2011</td>
|
||||
<td colspan="4">
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>
|
||||
Removed references to ACL (Access Control List).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Fixed error in examples referring to X-Auth-Key where it should be X-Auth-Token.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Added section numbers.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr><tr>
|
||||
<td colspan="1" align="center">Jan. 4, 2011</td>
|
||||
<td colspan="4">
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>
|
||||
Expanded authentication information for UK release.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Added "delimiter" as a Query Parameter and server-side object copy example.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1" align="center">May 5, 2008</td>
|
||||
<td colspan="4">
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Initial release.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
</section>
|
||||
<section xml:id="additional-resources-object-devguide">
|
||||
<title>Additional Resources</title>
|
||||
<para>You can download the most current version of this document from the OpenStack Docs
|
||||
website at <link
|
||||
xlink:href="http://docs.openstack.org">
|
||||
http://docs.openstack.org</link>. </para>
|
||||
<para> For more details about the Rackspace Cloud Files implementation of the OpenStack Object
|
||||
Storage service, please refer to <link
|
||||
xlink:href="www.rackspacecloud.com/cloud_hosting_products/files"
|
||||
>http://www.rackspacecloud.com/cloud_hosting_products/files</link>. Related documents are
|
||||
available at the same site, as are links to Rackspace's official support channels, including
|
||||
knowledge base articles, forums, phone, chat, and email. </para>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,183 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- 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="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="ch_object-storage-dev-troubleshooting">
|
||||
<title>Troubleshooting</title>
|
||||
<para>This section introduces a command-line utility, cURL, and demonstrates interacting with the ReST
|
||||
interfaces through that utility.</para>
|
||||
<section xml:id="using-curl-cli">
|
||||
<title>Using cURL</title>
|
||||
<para>cURL is a command-line tool which is available on most UNIX®-like environments and Mac
|
||||
OS X® and can be downloaded for Windows®. For more information on cURL, visit <link
|
||||
xlink:href="http://curl.haxx.se/">http://curl.haxx.se/</link>. </para>
|
||||
<para>cURL allows you to transmit and receive HTTP requests and responses from the
|
||||
command-line or from within a shell script. This makes it possible to work with the ReST API
|
||||
directly without using one of the client APIs. </para>
|
||||
<para>The following cURL command-line options will be used</para>
|
||||
<variablelist>
|
||||
<title>cURL Command-Line Options</title>
|
||||
<varlistentry>
|
||||
<term><option>-X METHOD</option></term>
|
||||
<listitem>
|
||||
<para>Specify the HTTP method to request (<code>HEAD</code>, &GET;,
|
||||
etc.)</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-D</option></term>
|
||||
<listitem>
|
||||
<para>Dump HTTP response headers to stdout.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-H HEADER</option></term>
|
||||
<listitem>
|
||||
<para>Specify an HTTP header in the request.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<section xml:id="authentication-examples-curl">
|
||||
<title>Authentication</title>
|
||||
<para>In order to use the ReST API, you will first need to obtain a authorization token,
|
||||
which will need to be passed in for each request using the <code>X-Auth-Token</code>
|
||||
header. The following example demonstrates how to use cURL to obtain the authorization
|
||||
token and the URL of the storage system.</para>
|
||||
<example>
|
||||
<title>cURL Authenticate</title>
|
||||
<screen>
|
||||
<command>curl</command> <option>-D</option> - \
|
||||
<option>-H "X-Auth-Key: jdoesecretpassword"</option> \
|
||||
<option>-H "X-Auth-User: jdoe"</option> \
|
||||
<uri>https://auth.api.yourcloud.com/v1.0</uri>
|
||||
</screen>
|
||||
<screen>
|
||||
<computeroutput>HTTP/1.1 204 No Content
|
||||
Date: Thu, 09 Jul 2009 15:31:39 GMT
|
||||
Server: Apache/2.2.3
|
||||
X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_343
|
||||
X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae
|
||||
Content-Length: 0
|
||||
Connection: close
|
||||
Content-Type: application/octet-stream
|
||||
</computeroutput></screen>
|
||||
</example>
|
||||
<para>The storage URL and authentication token are returned in
|
||||
the headers of the response. After authentication, you can use cURL to perform
|
||||
<code>HEAD</code>, &GET;, &DELETE;, &POST; and &PUT; requests on the storage
|
||||
service.</para>
|
||||
</section>
|
||||
<section xml:id="determining-storage-useage">
|
||||
<title>Determining Storage Usage</title>
|
||||
<para>A <code>HEAD</code> request can be sent to the storage service to determine how much
|
||||
data you have stored in the system and the number of containers you are using. Use the
|
||||
<code>-X</code> switch to specify the correct HTTP method and the <code>-D</code> to
|
||||
dump the HTTP response headers to terminal output (stdout).</para>
|
||||
<example>
|
||||
<title>cURL Get Storage Space</title>
|
||||
<screen>
|
||||
<command>curl</command> <option>–X HEAD</option> <option>-D</option> - \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri>
|
||||
</screen>
|
||||
<screen>
|
||||
<computeroutput>HTTP/1.1 204 No Content
|
||||
Date: Thu, 09 Jul 2009 15:38:14 GMT
|
||||
Server: Apache
|
||||
X-Account-Container-Count: 22
|
||||
X-Account-Bytes-Used: 9891628380
|
||||
Content-Type: text/plain
|
||||
</computeroutput></screen>
|
||||
</example>
|
||||
<para>The HTTP request must include a header to specify the authentication token. The HTTP
|
||||
headers in the response indicate the number of containers in this storage account and the
|
||||
total bytes stored for the entire account.</para>
|
||||
</section>
|
||||
<section xml:id="creating-a-storage-container">
|
||||
<title>Creating a Storage Container</title>
|
||||
<para> Before uploading any data to OpenStack Object Storage, you must create a storage container. You do
|
||||
this with a &PUT; request; cURL can be used for that, too.</para>
|
||||
<example>
|
||||
<title>cURL Create Storage Container</title>
|
||||
<screen>
|
||||
<command>curl</command> <option>–X PUT</option> <option>-D</option> - \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images</uri>
|
||||
</screen>
|
||||
<screen>
|
||||
<computeroutput>HTTP/1.1 201 Created
|
||||
Date: Thu, 09 Jul 2009 17:03:36 GMT
|
||||
Server: Apache
|
||||
Content-Length: 0
|
||||
Content-Type: text/plain
|
||||
</computeroutput></screen>
|
||||
</example>
|
||||
<para>Returning an HTTP status code of 201 (Created) indicates that the container was
|
||||
successfully created.</para>
|
||||
</section>
|
||||
<section xml:id="uploading-a-storage-object">
|
||||
<title>Uploading a Storage Object</title>
|
||||
<para>After creating a container, you can upload a local file. For this example, let's
|
||||
upload a screenshot image. The <code>-T</code> switch specifies the full path to the local
|
||||
file to upload. </para>
|
||||
<example>
|
||||
<title>cURL Upload Storage Object</title>
|
||||
<screen>
|
||||
<command>curl</command> <option>–X PUT</option> <option>-T screenies/wow1.jpg</option><option>-D</option> - \
|
||||
<option>-H "ETag: 805120ec285a7ed28f74024422fe3594"</option> \
|
||||
<option>-H "Content-Type: image/jpeg"</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-H "X-Object-Meta-Screenie: Mel visits Outland"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images/wow1.jpg</uri>
|
||||
</screen>
|
||||
<screen>
|
||||
<computeroutput>HTTP/1.1 201 Created
|
||||
Date: Thu, 09 Jul 2009 17:03:36 GMT
|
||||
Server: Apache
|
||||
Content-Length: 0
|
||||
Etag: 805120ec285a7ed28f74024422fe3594
|
||||
Content-Type: text/plain
|
||||
</computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="other-curl-commands">
|
||||
<title>Other cURL Commands</title>
|
||||
<para>You can issue any of the ReST methods defined for OpenStack Object Storage with the cURL utility.
|
||||
For example, you can use cURL to send &POST; and &DELETE; requests even though we haven't
|
||||
provided specific examples.</para>
|
||||
<para>Note that generally each time you invoke <code>curl</code> to perform an
|
||||
operation, the system creates a separate TCP/IP and SSL connection and then throws it away. The language
|
||||
APIs, however, are designed to re-use these connections between operations and therefore
|
||||
provide much better performance. We recommend that you use one of the supported
|
||||
language APIs in your production applications and limit <code>curl</code> to
|
||||
quick-and-easy testing/troubleshooting.</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- 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="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
xmlns:db="http://docbook.org/ns/docbook"
|
||||
version="5.0">
|
||||
<title>OpenStack Object Storage Developer Guide</title>
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
<firstname/>
|
||||
<surname/>
|
||||
</personname>
|
||||
<affiliation>
|
||||
<orgname>OpenStack</orgname>
|
||||
</affiliation>
|
||||
</author>
|
||||
<copyright>
|
||||
<year>2010</year>
|
||||
<year>2011</year>
|
||||
<holder>OpenStack, LLC</holder>
|
||||
</copyright>
|
||||
<releaseinfo>API v1</releaseinfo>
|
||||
<productname>OpenStack Object Storage</productname>
|
||||
<pubdate>2011-09-08</pubdate>
|
||||
<legalnotice role="apache2">
|
||||
<annotation>
|
||||
<remark>Copyright details are filled in by the template.</remark>
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
<abstract>
|
||||
<para> This document is intended for software developers interested in developing applications
|
||||
using the OpenStack™ Object Storage Application Programming Interface
|
||||
(<abbrev>API</abbrev>). </para>
|
||||
</abstract>
|
||||
<cover>
|
||||
<para>this is a placeholder for the front cover</para>
|
||||
</cover>
|
||||
<cover>
|
||||
<para>this is a placeholder for the back cover</para>
|
||||
|
||||
</cover>
|
||||
</info>
|
||||
|
||||
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
|
||||
<xi:include href="object-api-overview.xml"/>
|
||||
<xi:include href="object-api-general.xml"/>
|
||||
<xi:include href="object-api-storage-services.xml"/>
|
||||
<xi:include href="object-api-troubleshooting-examples.xml"/>
|
||||
</book>
|
||||
Loading…
Reference in New Issue