829 lines
41 KiB
XML
829 lines
41 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE application [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
<!ENTITY asterisk "*">
|
|
|
|
<!-- 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>'>
|
|
]>
|
|
<!-- (C) 2013 OpenStack Foundation, All Rights Reserved -->
|
|
<application xmlns="http://wadl.dev.java.net/2009/02"
|
|
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02"
|
|
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:db="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:csapi="http://docs.openstack.org/compute/api/v1.1">
|
|
<resources base="https://storage.swiftdrive.com/"
|
|
xml:id="object-v1">
|
|
<resource id="version" path="v1">
|
|
<resource id="account" path="{account}"
|
|
type="#ContainersList">
|
|
<param name="account" style="template"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<para>The unique identifier of the
|
|
tenant.</para></wadl:doc>
|
|
</param>
|
|
<method href="#retrieveaccountmeta"/>
|
|
<method href="#updateaccountmeta"/>
|
|
<method href="#deleteaccountmeta"/>
|
|
<resource id="container" path="{container}"
|
|
type="#ObjectsList">
|
|
<param name="container" style="template"
|
|
type="xsd:string">
|
|
<wadl:doc
|
|
xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<para>The unique identifier of the
|
|
container.</para></wadl:doc>
|
|
</param>
|
|
<method href="#createcontainer"/>
|
|
<method href="#deletecontainer"/>
|
|
<method href="#retrievecontainermeta"/>
|
|
<method href="#updateacontainermeta"/>
|
|
<resource id="object" path="{object}"
|
|
type="#RetrieveObject">
|
|
<param name="object" style="template"
|
|
type="xsd:string">
|
|
<wadl:doc
|
|
xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<para>The unique identifier of the
|
|
object.</para></wadl:doc>
|
|
</param>
|
|
<method href="#createobject"/>
|
|
<method href="#deleteobject"/>
|
|
<method href="#copyobject"/>
|
|
<method href="#retrieveobjectmeta"/>
|
|
<method href="#updateaobjmeta"/>
|
|
</resource>
|
|
</resource>
|
|
</resource>
|
|
</resource>
|
|
</resources>
|
|
<!--*******************************************************-->
|
|
<!-- Resource Types -->
|
|
<!--*******************************************************-->
|
|
<resource_type id="ContainersList">
|
|
<method href="#listContainers"/>
|
|
</resource_type>
|
|
<resource_type id="ObjectsList">
|
|
<method href="#listObjects"/>
|
|
</resource_type>
|
|
<resource_type id="RetrieveObject">
|
|
<method href="#retrieveobject"/>
|
|
</resource_type>
|
|
<!--*******************************************************-->
|
|
<!-- All Methods -->
|
|
<!--*******************************************************-->
|
|
<method name="GET" id="listContainers">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="List containers">
|
|
<para role="shortdesc">Lists storage containers, sorted by
|
|
name.</para>
|
|
<para>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>
|
|
<para>At this time, a prefix query parameter is not
|
|
supported at the account level.</para>
|
|
<para>A list of containers is returned in the response
|
|
body, one container per line.</para>
|
|
<para>The HTTP response status code is a value from 200 to
|
|
299, inclusive.</para>
|
|
<para><emphasis role="bold">Serialized list
|
|
output</emphasis></para>
|
|
<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>
|
|
<para><emphasis role="bold">Control a large number of
|
|
containers</emphasis></para>
|
|
<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. 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>
|
|
<para>Again, two items are returned, and there might be
|
|
more. You now receive a one-item response, which is
|
|
fewer than than the limit number of container names.
|
|
This indicates that this is the end of the list. By
|
|
using end_marker, you can limit the result set to
|
|
container names less than the specified value.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="limit" style="query" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>For an integer value
|
|
<replaceable>n</replaceable>, limits the
|
|
number of results to n
|
|
values.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="marker" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Given a string value
|
|
<replaceable>x</replaceable>, returns
|
|
container names greater in value than the
|
|
specified marker.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="end_marker" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Given a string value
|
|
<replaceable>x</replaceable>, returns
|
|
container names less in value than the
|
|
specified marker.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="format" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the serialized
|
|
response format. Either json or
|
|
xml.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"
|
|
title="Get container details request: HTTP with JSON">
|
|
<xsdxt:code
|
|
href="samples/getcontainer_details_httphead.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
<representation mediaType="application/xml">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"
|
|
title="Get container details request: HTTP with XML">
|
|
<xsdxt:code
|
|
href="samples/getcontainer_details_httphead_xml.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="200">
|
|
<representation mediaType="application/xml">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"
|
|
title="Get container details response: XML">
|
|
<xsdxt:code
|
|
href="samples/getcontainer_details_response.xml"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"
|
|
title="List containers response: JSON">
|
|
<xsdxt:code href="samples/containerlist.json"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
</method>
|
|
<method name="HEAD" id="retrieveaccountmeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Get account metadata">
|
|
<para role="shortdesc">Gets the number of containers and
|
|
the total bytes that are stored in Object Storage for
|
|
the tenant.</para>
|
|
<para>This information is returned in the
|
|
<code>X-Account-Container-Count</code> and
|
|
<code>X-Account-Bytes-Used</code>custom headers.
|
|
Because 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>
|
|
<para>If the request succeeds, the HTTP return code is
|
|
from 200 to 299, inclusive. An invalid account or
|
|
access key returns a 401 (Unauthorized) error
|
|
code.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param name="X-newest" style="header" type="xsd:boolean">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Set to <literal>True</literal>
|
|
in &HEAD; and &GET; requests to have Object
|
|
Storage query all replicas to return the most
|
|
recent one. If you omit this header, Object
|
|
Storage responds faster after it finds one
|
|
valid replica. Because setting this header to
|
|
<literal>True</literal> is more expensive
|
|
for the back-end, use it only when it is
|
|
absolutely needed.</para></wadl:doc>
|
|
</param>
|
|
</request>
|
|
<response status="204">
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Account-Container-Count" style="header"
|
|
required="true" type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The number of containers.
|
|
</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Account-Bytes-Used" style="header"
|
|
required="true" type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The count of bytes used in
|
|
total.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/getaccountmeta_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
<response status="401"/>
|
|
</method>
|
|
<method name="POST" id="updateaccountmeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Create or update account metadata">
|
|
<para role="shortdesc">Creates or updates account metadata
|
|
by associating custom metadata headers with the
|
|
account level URI. These headers must have the format,
|
|
<code>X-Account-Meta-<replaceable>name</replaceable></code>.</para>
|
|
<para>Subsequent requests for the same key/value pair
|
|
overwrite the previous value.</para>
|
|
<para>If the request succeeds, the HTTP return code is
|
|
from 200 to 299, inclusive.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Account-Meta-name" style="header" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The account metadata. The
|
|
<replaceable>name</replaceable> represents the name of metadata.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/updateaccountmeta_httphead.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="204"> </response>
|
|
</method>
|
|
<method name="POST" id="deleteaccountmeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Delete account metadata">
|
|
<para role="shortdesc">Deletes a metadata header.</para>
|
|
<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
|
|
<code>X-Remove-Account-Meta-<replaceable>name</replaceable>:</code>
|
|
<replaceable>arbitrary value</replaceable> header. For
|
|
example, <code>X-Remove-Account-Meta-Book: x</code>.
|
|
The arbitrary value is ignored.</para>
|
|
<para>If the request succeeds, the HTTP return code is
|
|
from 200 to 299, inclusive.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Remove-Account-Meta-name" style="header"
|
|
required="false" type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>If the tool you use to
|
|
communicate with Object Storage, such as older
|
|
versions of cURL, does not support empty
|
|
headers, send the
|
|
<code>X-Remove-Account-Meta-name:
|
|
arbitrary value</code> header. For
|
|
example, <code>X-Remove-Account-Meta-Book:
|
|
x</code>. The arbitrary value is
|
|
ignored.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/deleteaccountmeta_httphead.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="204"> </response>
|
|
</method>
|
|
<method name="PUT" id="createcontainer">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Create container">
|
|
<para role="shortdesc">Creates a container.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Container-Meta" style="header"
|
|
required="false" type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The custom container metadata.
|
|
The asterisk (*) represents the name of
|
|
metadata.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/createcontainer_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="201"> </response>
|
|
</method>
|
|
<method name="DELETE" id="deletecontainer">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Delete container">
|
|
<para role="shortdesc">Deletes an empty container.</para>
|
|
</wadl:doc>
|
|
<response status="204"> </response>
|
|
</method>
|
|
<method name="HEAD" id="retrievecontainermeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Get container metadata">
|
|
<para role="shortdesc">Gets container metadata, including
|
|
the number of objects and the total bytes of all
|
|
objects stored in the container.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param name="X-newest" style="header" type="xsd:boolean">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Set to <literal>True</literal>
|
|
in &HEAD; and &GET; requests to have Object
|
|
Storage query all replicas to return the most
|
|
recent one. If you omit this header, Object
|
|
Storage responds faster after it finds one
|
|
valid replica. Because setting this header to
|
|
<literal>True</literal> is more expensive
|
|
for the back-end, use it only when it is
|
|
absolutely needed.</para></wadl:doc>
|
|
</param>
|
|
</request>
|
|
<response status="204">
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Container-Object-Count" style="header"
|
|
required="true" type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The number of
|
|
objects.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Container-Bytes-Used" style="header"
|
|
required="true" type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The count of bytes used in
|
|
total. (stored in header)</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/getcontainermeta_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
</method>
|
|
<method name="POST" id="updateacontainermeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Create or update container metadata">
|
|
<para role="shortdesc">Creates or updates the arbitrary
|
|
container metadata by associating custom metadata
|
|
headers with the container level URI. These headers
|
|
must have the format, X-Container-Meta-*.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Container-Meta" style="header"
|
|
required="false" type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The container metadata. *
|
|
represents the name of
|
|
metadata.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/updatecontainermeta_httphead.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="204"> </response>
|
|
</method>
|
|
<method name="GET" id="listObjects">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="List objects">
|
|
<para role="shortdesc">Lists the objects stored in the
|
|
container.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="limit" style="query" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The number limit of
|
|
results.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="marker" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the marker, that the
|
|
object names greater in value than are
|
|
returned.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="end_marker" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the marker, that the
|
|
object names less in value than are
|
|
returned.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="prefix" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the prefix, which the
|
|
returned object names begin
|
|
with.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="format" style="query" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the serialized
|
|
response format, either json or
|
|
xml.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="delimiter" style="query" required="false"
|
|
type="xsd:char">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Value of the delimiter, that
|
|
all the object names nested in the container
|
|
are returned.</para></wadl:doc>
|
|
</param>
|
|
</request>
|
|
<response status="200">
|
|
<representation mediaType="application/xml"/>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/objectlist.json"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
</method>
|
|
<method name="GET" id="retrieveobject">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Get object data">
|
|
<para role="shortdesc">Gets data for a specified
|
|
object.</para>
|
|
<para>You can perform conditional &GET; requests by using
|
|
the following HTTP headers in the request:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>If-Match</literal></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>If-None-Match</literal></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>If-Modified-Since</literal></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>If-Unmodified-Since</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>These headers are documented in <link
|
|
xlink:href="http://www.ietf.org/rfc/rfc2616.txt"
|
|
>http://www.ietf.org/rfc/rfc2616.txt</link>.</para>
|
|
<para>You can use the HTTP <code>Range</code> header to
|
|
fetch portions of data by using one or more range
|
|
specifications. To specify many ranges, separate the
|
|
range specifications with a comma.</para>
|
|
<para>The types of range specifications are:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Byte range
|
|
specification</emphasis>. Use
|
|
FIRST_BYTE_OFFSET to specify the start of the
|
|
data range, and LAST_BYTE_OFFSET to specify
|
|
the end. You can omit the LAST_BYTE_OFFSET and
|
|
if you do, the value defaults to the offset of
|
|
the last byte of data.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Suffix byte range
|
|
specification</emphasis>. Use LENGTH bytes
|
|
to specify the length of the data
|
|
range.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The following forms of the header specify the
|
|
following ranges of data:</para>
|
|
<itemizedlist>
|
|
<listitem><para><code>Range: bytes=-5</code>. The last
|
|
five bytes.</para></listitem>
|
|
<listitem>
|
|
<para><code>Range: bytes=10-15</code>. The five
|
|
bytes of data after a 10-byte
|
|
offset.</para></listitem><listitem>
|
|
<para><code>Range: bytes=10-15,-5</code>. A
|
|
multi-part response that contains the last
|
|
five bytes and the five bytes of data after a
|
|
10-byte offset. The <code>Content-Type</code>
|
|
of the response is then
|
|
<code>multipart/byteranges</code>.</para></listitem>
|
|
<listitem>
|
|
<para><code>Range: bytes=4-6</code>. Bytes 4 to 6
|
|
inclusive.</para></listitem>
|
|
<listitem>
|
|
<para><code>Range: bytes=2-2</code>. Byte 2, the
|
|
third byte of the data.</para></listitem>
|
|
<listitem>
|
|
<para><code>Range: bytes=6-</code>. Byte 6 and
|
|
after.</para></listitem>
|
|
<listitem>
|
|
<para><code>Range: bytes=1-3,2-5</code>. A
|
|
multi-part response that contains bytes 1 to 3
|
|
inclusive, and bytes 2 to 5 inclusive. The
|
|
<code>Content-Type</code> of the response
|
|
is then
|
|
<code>multipart/byteranges</code>.</para></listitem>
|
|
</itemizedlist>
|
|
</wadl:doc>
|
|
<request>
|
|
<param name="X-newest" style="header" type="xsd:boolean">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Set to <literal>True</literal>
|
|
in &HEAD; and &GET; requests to have Object
|
|
Storage query all replicas to return the most
|
|
recent one. If you omit this header, Object
|
|
Storage responds faster after it finds one
|
|
valid replica. Because setting this header to
|
|
<literal>True</literal> is more expensive
|
|
for the back-end, use it only when it is
|
|
absolutely needed.</para></wadl:doc>
|
|
</param>
|
|
</request>
|
|
<response status="200">
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/getobj_http.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
</method>
|
|
<method name="PUT" id="createobject">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Create or update object">
|
|
<para role="shortdesc">Creates or updates the content and
|
|
metadata for a specified object.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="ETag" style="header" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The MD5 checksum of your
|
|
object's data. (stored in
|
|
header)</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="Content-Disposition" style="header"
|
|
required="false" type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The new browser behavior for
|
|
the file, so that the downloader can save the
|
|
file rather than displaying it using default
|
|
browser settings. Stored in
|
|
header.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="Content-Encoding" style="header"
|
|
required="false" type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The underlying media type of
|
|
the compressed file.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Delete-At" style="header" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The certain date, in the
|
|
format of a Unix Epoch timestamp, when the
|
|
object will be removed.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Delete-After" style="header" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The certain date, in the
|
|
format of a Unix Epoch timestamp, after which
|
|
the object will be removed. Stored in
|
|
header.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Object-Meta" style="header" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The custom object metadata. *
|
|
represents the name of
|
|
metadata.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/createobj_http.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="201"> </response>
|
|
</method>
|
|
<method name="PUT" id="putcopiedobject">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Copy object">
|
|
<para role="shortdesc">Copies an object to another object
|
|
in the OpenStack Object Storage system.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Copy-From" style="header" required="true"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The container and object name
|
|
of the <emphasis role="italic"
|
|
>source</emphasis> object in the form of
|
|
“/container/object”.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="Content-Length" style="header" required="true"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The content length, which is
|
|
zero under this situation.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/copyobj_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="201"> </response>
|
|
</method>
|
|
<method name="COPY" id="copyobject">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Copy object">
|
|
<para role="shortdesc">Copies an object to another object
|
|
with a new name in the Object Storage system.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="Destination" style="header" required="true"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The container and object name
|
|
of the destination object in the form of
|
|
<code>/container/object</code>.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/copyobj_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="201"> </response>
|
|
</method>
|
|
<method name="HEAD" id="retrieveobjectmeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Get object metadata">
|
|
<para role="shortdesc">Gets object metadata and other
|
|
standard HTTP headers.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param name="X-newest" style="header" type="xsd:boolean">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>Set to <literal>True</literal>
|
|
in &HEAD; and &GET; requests to have Object
|
|
Storage query all replicas to return the most
|
|
recent one. If you omit this header, Object
|
|
Storage responds faster after it finds one
|
|
valid replica. Because setting this header to
|
|
<literal>True</literal> is more expensive
|
|
for the back-end, use it only when it is
|
|
absolutely needed.</para></wadl:doc>
|
|
</param>
|
|
</request>
|
|
<response status="200">
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code href="samples/getobjmeta_httphead.msg"
|
|
/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</response>
|
|
</method>
|
|
<method name="POST" id="updateaobjmeta">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Update object metadata">
|
|
<para role="shortdesc">Updates arbitrary key/value
|
|
metadata. Metadata must be in the format
|
|
X-Object-Meta-*. You can also assign X-Delete-At or
|
|
X-Delete-After to expiring objects. You cannot use
|
|
this operation to change other headers, such as
|
|
Content-Type.</para>
|
|
</wadl:doc>
|
|
<request>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Object-Meta" style="header" required="false"
|
|
type="xsd:string">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The container metadata. *
|
|
represents the name of
|
|
metadata.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Delete-At" style="header" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The certain date, in the
|
|
format of a Unix Epoch timestamp, when the
|
|
object will be removed.</para></wadl:doc>
|
|
</param>
|
|
<param xmlns="http://wadl.dev.java.net/2009/02"
|
|
name="X-Delete-After" style="header" required="false"
|
|
type="xsd:int">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN"><para>The certain date, in the
|
|
format of a Unix Epoch timestamp, after which
|
|
the object is removed.</para></wadl:doc>
|
|
</param>
|
|
<representation mediaType="application/json">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook"
|
|
xml:lang="EN">
|
|
<xsdxt:code
|
|
href="samples/updateobjmeta_httphead.msg"/>
|
|
</wadl:doc>
|
|
</representation>
|
|
</request>
|
|
<response status="202"> </response>
|
|
</method>
|
|
<method name="DELETE" id="deleteobject">
|
|
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
|
|
title="Delete object">
|
|
<para role="shortdesc">Permanently deletes an object from
|
|
the OpenStack Object Storage system. In combination
|
|
with the © command, you can use © and then
|
|
&DELETE; to effectively move an object.</para>
|
|
</wadl:doc>
|
|
<response status="204"> </response>
|
|
</method>
|
|
</application>
|