47653c6aa7
Moves generalized info to API Reference Other patch adds backup extension info to API Reference Change-Id: I8abd1189c8948044047fa6cf19683c982f826c83
771 lines
30 KiB
XML
771 lines
30 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!-- 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 v2.0'>
|
|
<!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 v2 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>2013</year>
|
|
<year>2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright>
|
|
<releaseinfo>API v2 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 for software developers who develop
|
|
applications by using the OpenStack Block Storage Application
|
|
Programming Interface (<abbrev>API</abbrev>).</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<date>2014-08-13</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Removed and replaced WADL references with links to <link
|
|
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v2.html"
|
|
><citetitle>Block Storage API v2
|
|
(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>
|
|
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
|
<date>2014-05-01</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added Block Storage extensions to the API
|
|
operations chapter.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-02-23</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated API call descriptions to point to WADL
|
|
files.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-12-14</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Corrected code example for list volume details
|
|
request.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-05-22</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated the book title for consistency.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-21</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Corrected request and response examples in the API
|
|
operations chapter.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-10</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Adds information about backups.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-02-24</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 the
|
|
OpenStack Compute service.</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 assists 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>
|
|
<section xml:id="Additional_Resources-d1e532">
|
|
<title>Additional resources</title>
|
|
<para>You can download the latest 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>
|
|
<chapter 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>OpenStack Block Storage is a block-level storage solution
|
|
that enables you to: <itemizedlist>
|
|
<listitem>
|
|
<para>Mount drives to OpenStack Cloud Servers<trademark/> to
|
|
scale storage without paying for more compute
|
|
resources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Use high performance storage to serve database or
|
|
I/O-intensive applications.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
<para>You interact with Block Storage programmatically through the
|
|
Block Storage API as described in this guide.</para>
|
|
<note>
|
|
<para><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>
|
|
<listitem>
|
|
<para>Block Storage allows you to create backups of your
|
|
volumes to Object Storage for archival and disaster
|
|
recovery purposes. These backups can be subsequently
|
|
restored to the same volume or new volumes.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</note>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Concepts">
|
|
<title>Glossary</title>
|
|
<?dbhtml stop-chunking?>
|
|
<para>To use the Block Storage API effectively, you must
|
|
understand several key concepts:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Volume</emphasis></para>
|
|
<para>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>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Volume type</emphasis></para>
|
|
<para>A type of a block storage volume. You can 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 can 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>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Snapshot</emphasis></para>
|
|
<para>A point in time copy of the data contained in a
|
|
volume.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Instance</emphasis></para>
|
|
<para>A virtual machine (VM) that runs inside the
|
|
cloud.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Backup</emphasis></para>
|
|
<para>A full copy of a volume stored in an external service.
|
|
The service can be configured. The only supported service
|
|
for now is Object Storage. A backup can subsequently be
|
|
restored from the external service to either the same
|
|
volume that the backup was originally taken from, or to a
|
|
new volume.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="High_Level_Task_Flow">
|
|
<title>High-level task flow</title>
|
|
<procedure>
|
|
<title>To create and attach a volume</title>
|
|
<step>
|
|
<para>You create a volume.</para>
|
|
<para>For example, you might create a 30 GB volume called
|
|
<literal>vol1</literal>, as follows:</para>
|
|
<screen><prompt>$</prompt> <userinput>cinder create --display-name vol1 30</userinput></screen>
|
|
<para>The command returns the
|
|
<literal>521752a6-acf6-4b2d-bc7a-119f9148cd8c</literal>
|
|
volume ID.</para>
|
|
</step>
|
|
<step>
|
|
<para>You attach that volume to a virtual machine (VM) with
|
|
the
|
|
<literal>616fb98f-46ca-475e-917e-2563e5a8cd19</literal>
|
|
ID, as follows:</para>
|
|
<para>For example:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="General_API_Information">
|
|
<title>General API information</title>
|
|
<para>The Block Storage API is implemented using a ReSTful web
|
|
service interface. Like other OpenStack projects, Block Storage
|
|
shares a common token-based authentication system that allows
|
|
access between products and services.</para>
|
|
<note>
|
|
<para>All requests to authenticate against and operate the
|
|
service are performed using SSL over HTTP (HTTPS) on TCP port
|
|
443.</para>
|
|
</note>
|
|
<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, and send the token to a service.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Get an authentication token by providing your user
|
|
name 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
|
|
user name and your password.</emphasis></para>
|
|
<screen><prompt>$</prompt> <userinput>curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</userinput></screen>
|
|
<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 programmatically parse an authentication
|
|
response, 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 that 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>Request with headers: Get volume types</title>
|
|
<literallayout class="monospaced">GET /&VERSION;/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>An XML response format is returned:</para>
|
|
<example>
|
|
<title>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-7'?>
|
|
<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="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>The following table shows the absolute limits:</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</td>
|
|
<td colspan="1">1 TB</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
</section>
|
|
<section xml:id="datetimeformat">
|
|
<title>Date and time format</title>
|
|
<para>Block Storage 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>May 19th, 2011 at 8:07:08 AM, GMT-5 has the following
|
|
format:</para>
|
|
<programlisting>2011-05-19T08:07:08-05:00</programlisting>
|
|
</example>
|
|
<para>The following table describes the date time format
|
|
codes:</para>
|
|
<table rules="all">
|
|
<caption>Date 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, Block Storage returns a fault object
|
|
containing an HTTP error response code that denotes the type
|
|
of error. The response body returns 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" width="100%">
|
|
<col width="20%"/>
|
|
<col width="15%"/>
|
|
<col width="65%"/>
|
|
<thead>
|
|
<tr align="center">
|
|
<td>Fault type</td>
|
|
<td>Associated error code</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>badRequest</code></td>
|
|
<td>400</td>
|
|
<td>The user request contains one or more errors.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unauthorized</code></td>
|
|
<td>401</td>
|
|
<td>The supplied token is not authorized to access the
|
|
resources, either it's expired or invalid.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>forbidden</code></td>
|
|
<td>403</td>
|
|
<td>Access to the requested resource was denied.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>itemNotFound</code></td>
|
|
<td>404</td>
|
|
<td>The back-end services did not find anything matching
|
|
the Request-URI.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>badMethod</code></td>
|
|
<td>405</td>
|
|
<td>The request method is not allowed for this
|
|
resource.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>overLimit</code></td>
|
|
<td>413</td>
|
|
<td>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><code>badMediaType</code></td>
|
|
<td>415</td>
|
|
<td>The requested content type is not supported by this
|
|
service.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unprocessableEntity</code></td>
|
|
<td>422</td>
|
|
<td>The requested resource could not be processed on at
|
|
the moment.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>instanceFault</code></td>
|
|
<td>500</td>
|
|
<td>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><code>notImplemented</code></td>
|
|
<td>501</td>
|
|
<td>The requested method or resource is not
|
|
implemented.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>serviceUnavailable</code></td>
|
|
<td>503</td>
|
|
<td>Block Storage 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 response: XML</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 response: JSON</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>The following two <code>badRequest</code> examples show
|
|
errors when the volume size is invalid:</para>
|
|
<example>
|
|
<title>Example badRequest fault on volume size errors:
|
|
XML</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 on volume size errors:
|
|
JSON</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 next two examples show <code>itemNotFound</code>
|
|
errors:</para>
|
|
<example>
|
|
<title>Example itemNotFound fault: XML</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</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 and extensions</title>
|
|
<para>For information about Block Storage API operations and extensions, see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v2.html"
|
|
><citetitle>Block Storage API v2 (CURRENT)</citetitle></link>.</para>
|
|
</chapter>
|
|
</book>
|