47653c6aa7
Moves generalized info to API Reference Other patch adds backup extension info to API Reference Change-Id: I8abd1189c8948044047fa6cf19683c982f826c83
729 lines
29 KiB
XML
729 lines
29 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!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 PRODNAME "OpenStack Block Storage">
|
|
<!ENTITY API 'Block Storage API v1'>
|
|
<!ENTITY VERSION 'v2'>
|
|
<!ENTITY PRODABBV "">
|
|
<!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"
|
|
xml:id="openstack-blockstorage-devguide">
|
|
<title>OpenStack Block Storage API v1 Reference</title>
|
|
<?rax title.font.size="28px" subtitle.font.size="28px"?>
|
|
<titleabbrev>Block Storage API Reference</titleabbrev>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>OpenStack Foundation</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<copyright>
|
|
<year>2010-2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright>
|
|
<releaseinfo>API v1 and extensions</releaseinfo>
|
|
<productname>OpenStack Block Storage</productname>
|
|
<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 &PRODNAME;
|
|
Application Programming Interface
|
|
(<abbrev>API</abbrev>).</para>
|
|
</abstract>
|
|
<revhistory 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">
|
|
<revision>
|
|
<date>2014-08-05</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Removed and replaced WADL references with link to <link
|
|
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v1.html"
|
|
><citetitle>Block Storage API v1
|
|
(CURRENT)</citetitle></link>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-06-17</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added common response status codes returned by
|
|
Block Storage.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-02-18</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated v1 documentation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-12-17</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Edits to initial version.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-10-17</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial release.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
</info>
|
|
<preface xml:id="Preface">
|
|
<title>Preface</title>
|
|
<para>OpenStack Block Storage provides volume management with
|
|
OpenStack Compute.</para>
|
|
<para>This document describes the features available with the
|
|
&API;.</para>
|
|
<para>We welcome feedback, comments and bug reports at <link
|
|
xlink:href="http://bugs.launchpad.net/cinder"
|
|
>bugs.launchpad.net/Cinder</link>.</para>
|
|
<section xml:id="Intended_Audience-d1e122">
|
|
<title>Intended audience</title>
|
|
<para>This guide is for software developers who develop
|
|
applications by using the &API;. It assumes the reader has a
|
|
general understanding of storage and is familiar with:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>ReSTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>HTTP/1.1 conventions</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or XML data serialization formats</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Additional_Resources-d1e532">
|
|
<title>Resources</title>
|
|
<para>You can download the most current versions of the
|
|
API-related documents from <link
|
|
xlink:href="http://docs.openstack.org/api/"
|
|
>docs.openstack.org/api/</link>.</para>
|
|
<para>This API uses standard HTTP 1.1 response codes as
|
|
documented at: <link
|
|
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
|
|
>www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.</para>
|
|
</section>
|
|
</preface>
|
|
<preface xml:id="Overview" 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">
|
|
<title>Overview</title>
|
|
<para>&PRODNAME; is a block-level storage solution that allows
|
|
customers to mount drives or volumes to their OpenStack Compute
|
|
servers<trademark/>. The two primary use cases are (1) to allow
|
|
customers to scale their storage independently from their
|
|
compute resources, and (2) to allow customers to utilize high
|
|
performance storage to serve database or I/O-intensive
|
|
applications.</para>
|
|
<para>Interactions with Block Storage occur programmatically via
|
|
the Block Storage API as described in this Developer
|
|
Guide.</para>
|
|
<para>Highlights of &PRODNAME; include:<itemizedlist>
|
|
<listitem>
|
|
<para>Mount a drive to a Compute server to scale storage
|
|
without paying for more compute capability.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<note>
|
|
<title>Notes</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>&PRODNAME; is an add-on feature to OpenStack Nova
|
|
Compute in Folsom versions and earlier.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Block Storage is multi-tenant rather than
|
|
dedicated.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Block Storage allows you to create snapshots that you
|
|
can save, list, and restore.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</note>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Concepts">
|
|
<title>Glossary</title>
|
|
<?dbhtml stop-chunking?>
|
|
<para>To use the &PRODNAME; API effectively, you should
|
|
understand several key concepts:</para>
|
|
<section xml:id="Volume">
|
|
<title>Volume</title>
|
|
<para>A volume is a detachable block storage device. You can
|
|
think of it as a USB hard drive. It can only be attached to
|
|
one instance at a time.</para>
|
|
</section>
|
|
<section xml:id="Snapshot">
|
|
<title>Snapshot</title>
|
|
<para>A snapshot is a point in time copy of the data contained
|
|
in a volume.</para>
|
|
</section>
|
|
<section xml:id="Volumetype">
|
|
<title>Volume type</title>
|
|
<para>The volume type is the type of a block storage volume.
|
|
You may define whatever types work best for you, such as
|
|
SATA, SCSCI, SSD, etc. These can be customized or defined by
|
|
the OpenStack admin.</para>
|
|
<para>You may also define extra_specs associated with your
|
|
volume types. For instance, you could have a
|
|
VolumeType=SATA, with extra_specs (RPM=10000, RAID-Level=5)
|
|
. Extra_specs are defined and customized by the
|
|
admin.</para>
|
|
</section>
|
|
<section xml:id="Instance">
|
|
<title>Instance</title>
|
|
<para>An instance is a virtual machine that runs inside the
|
|
cloud.</para>
|
|
</section>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="High_Level_Task_Flow">
|
|
<title>High-level task flow</title>
|
|
<para>The high-level task flow for Cinder is as follows:</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The tenant creates a volume.</para>
|
|
<para>For example, the tenant creates a 30G volume called
|
|
vol1.</para>
|
|
<programlisting language="bash" role="gutter: false"><prompt>$</prompt>cinder create --display-name vol1 30</programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>This gives the tenant a volume id
|
|
521752a6-acf6-4b2d-bc7a-119f9148cd8c. The tenant
|
|
attaches that volume to a virtual machine (VM)
|
|
616fb98f-46ca-475e-917e-2563e5a8cd19:</para>
|
|
<para>For example A:</para>
|
|
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb</programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
</preface>
|
|
<chapter xml:id="General_API_Information"
|
|
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">
|
|
<title>General API information</title>
|
|
<section xml:id="Authentication-d1e647">
|
|
<title>Authentication</title>
|
|
<para>You can use <link xlink:href="http://curl.haxx.se/"
|
|
>cURL</link> to try the authentication process in two steps:
|
|
get a token; send the token to a service.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Get an authentication token by providing your username
|
|
and either your API key or your password. Here are
|
|
examples of both approaches:</para>
|
|
<para><emphasis>You can request a token by providing your
|
|
username and your password.</emphasis></para>
|
|
<para>
|
|
<literallayout class="monospaced">curl -X POST https://auth.api.openstackcloud.com/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</literallayout>
|
|
</para>
|
|
<para>Successful authentication returns a token which you
|
|
can use as evidence that your identity has already been
|
|
authenticated. To use the token, pass it to other services
|
|
as an <code>X-Auth-Token</code> header.</para>
|
|
<para>Authentication also returns a service catalog, listing
|
|
the endpoints you can use for Cloud services.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Use the authentication token to send a GET to a
|
|
service you would like to use.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>Authentication tokens are typically valid for 24 hours.
|
|
Applications should be designed to re-authenticate after
|
|
receiving a 401 (Unauthorized) response from a service
|
|
endpoint.</para>
|
|
<important>
|
|
<para>If you are programmatically parsing an authentication
|
|
response, please be aware that service names are stable for
|
|
the life of the particular service and can be used as keys.
|
|
You should also be aware that a user's service catalog can
|
|
include multiple uniquely-named services which perform
|
|
similar functions.</para>
|
|
</important>
|
|
</section>
|
|
<section xml:id="Request_Response_Types-d1e903">
|
|
<title>Request and response types</title>
|
|
<para>The Block Storage API supports both the JSON and XML data
|
|
serialization formats. The request format is specified using
|
|
the <code>Content-Type</code> header and is required for calls
|
|
that have a request body. The response format can be specified
|
|
in requests either by using the <code>Accept</code> header or
|
|
by adding an <code>.xml</code> or <code>.json</code> extension
|
|
to the request URI. Note that it is possible for a response to
|
|
be serialized using a format different from the request. If no
|
|
response format is specified, JSON is the default. If
|
|
conflicting formats are specified using both an
|
|
<code>Accept</code> header and a query extension, the query
|
|
extension takes precedence.</para>
|
|
<para security="writeronly">Some operations support an Atom
|
|
representation that can be used to efficiently determine when
|
|
the state of services has changed.</para>
|
|
<table rules="all">
|
|
<caption>Response formats</caption>
|
|
<thead>
|
|
<tr align="center">
|
|
<td>Format</td>
|
|
<td>Accept header</td>
|
|
<td>Query extension</td>
|
|
<td>Default</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>JSON</td>
|
|
<td>application/json</td>
|
|
<td>.json</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XML</td>
|
|
<td>application/xml</td>
|
|
<td>.xml</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>In the request example below, notice that
|
|
<parameter>Content-Type</parameter> is set to
|
|
<parameter>application/json</parameter>, but
|
|
<parameter>application/xml</parameter> is requested via the
|
|
<parameter>Accept</parameter> header:</para>
|
|
<example>
|
|
<title>Get volume types: Request with headers</title>
|
|
<literallayout class="monospaced">
|
|
GET /v1/441446/types HTTP/1.1
|
|
Host: dfw.blockstorage.api.openstackcloud.com
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
|
Accept: application/xml
|
|
</literallayout>
|
|
</example>
|
|
<para><?rax-fo keep-with-next?>Therefore an XML response format
|
|
is returned:</para>
|
|
<example>
|
|
<title>Get volume types: Response with headers</title>
|
|
<literallayout class="monospaced">
|
|
HTTP/1.1 200 OK
|
|
Date: Fri, 20 Jul 2012 20:32:13 GMT
|
|
Content-Length: 187
|
|
Content-Type: application/xml
|
|
X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
|
|
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
<volume_types>
|
|
<volume_type id="1" name="SATA">
|
|
<extra_specs/>
|
|
</volume_type>
|
|
<volume_type id="2" name="SSD">
|
|
<extra_specs/>
|
|
</volume_type>
|
|
</volume_types>
|
|
</literallayout>
|
|
</example>
|
|
</section>
|
|
<xi:include href="../v2/section_http_status_codes.xml"/>
|
|
<section xml:id="Limits-d1e1208">
|
|
<title>Limits</title>
|
|
<para>All accounts, by default, have a preconfigured set of
|
|
thresholds (or limits) to manage capacity and prevent abuse of
|
|
the system. The system recognizes two kinds of limits:
|
|
<firstterm>rate limits</firstterm> and <firstterm>absolute
|
|
limits</firstterm>. Rate limits are thresholds that are
|
|
reset after a certain amount of time passes. Absolute limits
|
|
are fixed.</para>
|
|
<section xml:id="Rate_Limits-d1e1222" security="writeronly">
|
|
<title>Rate limits</title>
|
|
<para>Rate limits are specified in terms of both a
|
|
human-readable wild-card URI and a machine-processable
|
|
regular expression. The regular expression boundary matcher
|
|
'^' takes effect after the root URI path. For example, the
|
|
regular expression ^/v1.0/instances would match the bolded
|
|
portion of the following URI:
|
|
https://dfw.blockstorage.api.openstackcloud.com<emphasis
|
|
role="bold">/v1.0/instances</emphasis>.</para>
|
|
<para>The following table specifies the default rate limits
|
|
for all API operations for all &GET;, &POST;, &PUT;, and
|
|
&DELETE; calls for volumes:</para>
|
|
<table rules="all">
|
|
<caption>Default rate limits</caption>
|
|
<thead>
|
|
<tr align="center">
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="2">URI</td>
|
|
<td colspan="2">RegEx</td>
|
|
<td colspan="1">Default</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">&GET; changes-since</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
|
|
<td colspan="1">3/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&POST;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
|
|
<td colspan="1">10/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&POST; instances</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
|
|
<td colspan="1">50/day</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&PUT;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
|
|
<td colspan="1">10/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&DELETE;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
|
|
<td colspan="1">100/minute</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>Rate limits are applied in order relative to the verb,
|
|
going from least to most specific. For example, although the
|
|
threshold for &POST; to /v1.0/* is 10 per minute, one cannot
|
|
&POST; to /v1.0/* more than 50 times within a single
|
|
day.</para>
|
|
<para>If you exceed the thresholds established for your
|
|
account, a <errorcode>413 (Rate Control)</errorcode> HTTP
|
|
response will be returned with a <code>Retry-After</code>
|
|
header to notify the client when it can attempt to try
|
|
again.</para>
|
|
</section>
|
|
<section xml:id="Absolute_Limits-d1e1397">
|
|
<title>Absolute limits</title>
|
|
<para>Refer to the following table for the absolute limits
|
|
that are set.</para>
|
|
<table rules="all">
|
|
<caption>Absolute limits</caption>
|
|
<col width="120pt"/>
|
|
<col width="201pt"/>
|
|
<col width="50pt"/>
|
|
<thead>
|
|
<tr>
|
|
<td colspan="1">Name</td>
|
|
<td colspan="1">Description</td>
|
|
<td colspan="1">Limit</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">Block Storage</td>
|
|
<td colspan="1">Maximum amount of block storage (in
|
|
gigabytes)</td>
|
|
<td colspan="1">1 TB</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
</section>
|
|
<section xml:id="datetimeformat">
|
|
<title>Date and time format</title>
|
|
<para>The Block Storage Service uses an ISO-8601 compliant date
|
|
format for the display and consumption of date/time
|
|
values.</para>
|
|
<example>
|
|
<title>DB service date and time format</title>
|
|
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
|
|
<para>See the table below for a description of the date/time
|
|
format codes.</para>
|
|
<para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have the
|
|
following format:</para>
|
|
<programlisting>2011-05-19T08:07:08-05:00</programlisting>
|
|
</example>
|
|
<table rules="all">
|
|
<caption>Date and time format codes</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>Code</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>yyyy</td>
|
|
<td>Four digit year</td>
|
|
</tr>
|
|
<tr>
|
|
<td>MM</td>
|
|
<td>Two digit month</td>
|
|
</tr>
|
|
<tr>
|
|
<td>dd</td>
|
|
<td>Two digit day of month</td>
|
|
</tr>
|
|
<tr>
|
|
<td>T</td>
|
|
<td>Separator for date/time</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HH</td>
|
|
<td>Two digit hour of day (00-23)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>mm</td>
|
|
<td>Two digit minutes of hour</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ss</td>
|
|
<td>Two digit seconds of the minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>SSS</td>
|
|
<td>Three digit milliseconds of the second</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Z</td>
|
|
<td>RFC-822 timezone</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
|
|
<section xml:id="DB_faults">
|
|
<title>Faults</title>
|
|
<para>When an error occurs, the Block Storage Service returns a
|
|
fault object containing an HTTP error response code that
|
|
denotes the type of error. In the body of the response, the
|
|
system will return additional information about the
|
|
fault.</para>
|
|
<para>The following table lists possible fault types with their
|
|
associated error codes and descriptions.</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr align="center">
|
|
<td colspan="2">Fault Type</td>
|
|
<td colspan="1">Associated Error Code</td>
|
|
<td colspan="3">Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="2"><code>badRequest</code></td>
|
|
<td colspan="1">400</td>
|
|
<td colspan="3">There was one or more errors in the user
|
|
request.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>unauthorized</code></td>
|
|
<td colspan="1">401</td>
|
|
<td colspan="3">The supplied token is not authorized to
|
|
access the resources, either it's expired or
|
|
invalid.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>forbidden</code></td>
|
|
<td colspan="1">403</td>
|
|
<td colspan="3">Access to the requested resource was
|
|
denied.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>itemNotFound</code></td>
|
|
<td colspan="1">404</td>
|
|
<td colspan="3">The back-end services did not find
|
|
anything matching the Request-URI.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>badMethod</code></td>
|
|
<td colspan="1">405</td>
|
|
<td colspan="3">The request method is not allowed for this
|
|
resource.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>overLimit</code></td>
|
|
<td colspan="1">413</td>
|
|
<td colspan="3">Either the number of entities in the
|
|
request is larger than allowed limits, or the user has
|
|
exceeded allowable request rate limits. See the
|
|
<code>details</code> element for more specifics.
|
|
Contact support if you think you need higher request
|
|
rate limits.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>badMediaType</code></td>
|
|
<td colspan="1">415</td>
|
|
<td colspan="3">The requested content type is not
|
|
supported by this service.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>unprocessableEntity</code></td>
|
|
<td colspan="1">422</td>
|
|
<td colspan="3">The requested resource could not be
|
|
processed on at the moment.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>instanceFault</code></td>
|
|
<td colspan="1">500</td>
|
|
<td colspan="3">This is a generic server error and the
|
|
message contains the reason for the error. This error
|
|
could wrap several error messages and is a catch
|
|
all.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>notImplemented</code></td>
|
|
<td colspan="1">501</td>
|
|
<td colspan="3">The requested method or resource is not
|
|
implemented.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><code>serviceUnavailable</code></td>
|
|
<td colspan="1">503</td>
|
|
<td colspan="3">The Block Storage Service is not
|
|
available.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<para>The following two <code>instanceFault</code> examples show
|
|
errors when the server has erred or cannot perform the
|
|
requested operation:</para>
|
|
<example>
|
|
<title>Example instancefault: XML response</title>
|
|
<screen><computeroutput>HTTP/1.1 500 Internal Server Error
|
|
Content-Type: application/xml
|
|
Content-Length: 121
|
|
Date: Mon, 28 Nov 2011 18:19:37 GMT</computeroutput></screen>
|
|
<programlisting language="xml"><xi:include href="samples/db-faults-instanceFault.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example fault: JSON response</title>
|
|
<screen><computeroutput>HTTP/1.1 500 Internal Server Error
|
|
Content-Length: 120
|
|
Content-Type: application/json; charset=UTF-8
|
|
Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
|
|
<programlisting language="json"><xi:include href="samples/db-faults-instanceFault.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>The error code (<code>code</code>) is returned in the body
|
|
of the response for convenience. The <code>message</code>
|
|
element returns a human-readable message that is appropriate
|
|
for display to the end user. The <code>details</code> element
|
|
is optional and may contain information that is useful for
|
|
tracking down an error, such as a stack trace. The
|
|
<code>details</code> element may or may not be appropriate
|
|
for display to an end user, depending on the role and
|
|
experience of the end user.</para>
|
|
<para>The fault's root element (for example,
|
|
<code>instanceFault</code>) may change depending on the type
|
|
of error.</para>
|
|
<para><?rax-fo keep-with-next?>The following
|
|
<code>badRequest</code> examples show errors when the volume
|
|
size is not valid:</para>
|
|
<example>
|
|
<title>Example badRequest fault and volume size errors: XML
|
|
request</title>
|
|
<screen><computeroutput>HTTP/1.1 400 None
|
|
Content-Type: application/xml
|
|
Content-Length: 121
|
|
Date: Mon, 28 Nov 2011 18:19:37 GMT</computeroutput></screen>
|
|
<programlisting language="xml"><xi:include href="samples/db-faults-badRequest.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example badRequest fault and volume size errors: JSON
|
|
request</title>
|
|
<screen><computeroutput>HTTP/1.1 400 None
|
|
Content-Length: 120
|
|
Content-Type: application/json; charset=UTF-8
|
|
Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
|
|
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>The following examples show <code>itemNotFound</code>
|
|
errors:</para>
|
|
<example>
|
|
<title>Example itemNotFound fault: XML response</title>
|
|
<screen><computeroutput>HTTP/1.1 404 Not Found
|
|
Content-Length: 147
|
|
Content-Type: application/xml; charset=UTF-8
|
|
Date: Mon, 28 Nov 2011 19:50:15 GMT</computeroutput></screen>
|
|
<programlisting language="xml"><xi:include href="samples/db-faults-itemNotFound.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example itemNotFound fault: JSON response</title>
|
|
<screen><computeroutput>HTTP/1.1 404 Not Found
|
|
Content-Length: 78
|
|
Content-Type: application/json; charset=UTF-8
|
|
Date: Tue, 29 Nov 2011 00:35:24 GMT</computeroutput></screen>
|
|
<programlisting language="json"><xi:include href="samples/db-faults-itemNotFound.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="API_Operations"
|
|
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">
|
|
<title>API operations</title>
|
|
<para>For information about Block Storage API operations, see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v1.html"
|
|
><citetitle>Block Storage API v1 (CURRENT)</citetitle></link>.</para>
|
|
</chapter>
|
|
</book>
|