d813475bc0
Cinder API docs doesn't include Error responses. This change adds details about the common response status codes returned by the Block Storage Service. Changes include modification both at the v2 and v1 layer. Closes-Bug: #1244395 Change-Id: I08f4c3d32e57b56c82f35663f6aed12a706f4a8d
823 lines
33 KiB
XML
823 lines
33 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-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>
|
|
<section xml:id="Volumes">
|
|
<title>Volumes</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>
|
|
<para><?rax-fo keep-with-next?>When making an API call to
|
|
create, list, or delete volume(s), the following status values
|
|
are possible:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>CREATING – The volume is being created.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AVAILABLE – The volume is read to be attached to
|
|
an instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ATTACHING – The volume is attaching to an
|
|
instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>IN-USE – The volume is attached to an
|
|
instance.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DELETING – The volume is being deleted.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR – An error has occurred with the
|
|
volume.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR_DELETING – There was an error deleting the
|
|
volume.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#volumes">
|
|
<wadl:method href="createVolume"/>
|
|
<wadl:method href="getVolumesSimple"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#detail-volume">
|
|
<wadl:method href="getVolumesDetail"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#volume_id">
|
|
<wadl:method href="getVolume"/>
|
|
<wadl:method href="deleteVolume"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="Snapshots">
|
|
<title>Snapshots</title>
|
|
<para><?rax-fo keep-with-next?>A snapshot is a point in time
|
|
copy of the data contained in a volume.</para>
|
|
<para>When making an API call to create, list, or delete
|
|
snapshot(s), the following status values are possible:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>CREATING – The snapshot is being created.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AVAILABLE – The snapshot is ready to be
|
|
used.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DELETING – The snapshot is being deleted.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR – An error occurred with the
|
|
snapshot.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR_DELETING – There was an error deleting the
|
|
snapshot.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#snapshots"/>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#detail-snapshots"/>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/volume-api-v1.wadl#snapshot_id"
|
|
/>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="Volume_Types">
|
|
<title>Volume types</title>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#types">
|
|
<wadl:method href="getVolumeTypes"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#volume_type_id">
|
|
<wadl:method href="getVolumeType"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="ext-os-quota-sets-cinder">
|
|
<title>Quota sets extension (os-quota-sets)</title>
|
|
<para>Administrators only, depending on policy settings. View,
|
|
update, and delete quotas for a tenant.</para>
|
|
<wadl:resources
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v1/os-quota-sets.wadl"
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
|
|
</section>
|
|
</chapter>
|
|
</book>
|