openstack-attic/volume-api
Code Issues Proposed changes

Remove extra whitespace

Browse Source 
Remove unneeded whitespace like end of line whitespace or
whitespace before </param>.

Change-Id: I87aa31d7f97e8ba5de5192ccbba47c914bfb11c0
This commit is contained in:
Andreas Jaeger 2013-12-26 18:59:16 +01:00
parent 72e365e0fa
commit e52fbcb8ec
5 changed files with 163 additions and 171 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
src/wadls/volume-api/src/os-volume-1.wadl
View File

@ -56,7 +56,7 @@
</resource> </resource>
<resource id="snapshots" path="snapshots"> <resource id="snapshots" path="snapshots">
<doc title="Snapshots"/> <doc title="Snapshots"/>
<method href="#createSnapshot" /> <method href="#createSnapshot" />
<method href="#getSnapshotsSimple" /> <method href="#getSnapshotsSimple" />
@ -170,8 +170,6 @@
the specified {server_id}). the specified {server_id}).
</p></doc> </p></doc>
</representation> </representation>
</response> </response>
</method> </method>
@ -336,7 +334,6 @@
</doc> </doc>
</param> </param>
<representation mediaType="application/xml"> <representation mediaType="application/xml">
<doc xml:lang="EN"> <doc xml:lang="EN">
<xsdxt:code href="samples/snapshot_create.xml" /> <xsdxt:code href="samples/snapshot_create.xml" />

94
v1/src/openstack-blockstorage-devguide.xml
View File

@ -55,7 +55,7 @@ format="SVG" scale="60"/>
</legalnotice> </legalnotice>
<abstract> <abstract>
<para>This document is intended for software developers interested in developing applications <para>This document is intended for software developers interested in developing applications
using the &PRODNAME; Application Programming Interface (<abbrev>API</abbrev>). </para> using the &PRODNAME; Application Programming Interface (<abbrev>API</abbrev>).</para>
</abstract> </abstract>
<revhistory xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" <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"> xmlns:html="http://www.w3.org/1999/xhtml">
@ -101,7 +101,7 @@ format="SVG" scale="60"/>
<title>Intended Audience</title> <title>Intended Audience</title>
<para>This Guide is intended to assist software developers who want to develop applications <para>This Guide is intended to assist software developers who want to develop applications
using the &APIv1;. It assumes the reader has a general understanding of storage and is using the &APIv1;. It assumes the reader has a general understanding of storage and is
familiar with: </para> familiar with:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>ReSTful web services</para> <para>ReSTful web services</para>
@ -120,10 +120,10 @@ format="SVG" scale="60"/>
<section xml:id="Additional_Resources-d1e532"> <section xml:id="Additional_Resources-d1e532">
<title>Additional Resources</title> <title>Additional Resources</title>
<para>You can download the most current versions of the API-related documents from <link <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> 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 <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" xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
>www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>. </para> >www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.</para>
</section> </section>
</preface> </preface>
<preface xml:id="Overview" xmlns:svg="http://www.w3.org/2000/svg" <preface xml:id="Overview" xmlns:svg="http://www.w3.org/2000/svg"
@ -133,9 +133,9 @@ format="SVG" scale="60"/>
volumes to their OpenStack Compute servers<trademark/>. The two primary use cases are (1) to 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 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 allow customers to utilize high performance storage to serve database or I/O-intensive
applications. </para> applications.</para>
<para>Interactions with Block Storage occur programmatically via the Block Storage API as <para>Interactions with Block Storage occur programmatically via the Block Storage API as
described in this Developer Guide. </para> described in this Developer Guide.</para>
<para>Highlights of &PRODNAME; include:<itemizedlist> <para>Highlights of &PRODNAME; include:<itemizedlist>
<listitem> <listitem>
<para>Mount a drive to a Compute server to scale storage without paying for more compute <para>Mount a drive to a Compute server to scale storage without paying for more compute
@ -163,11 +163,11 @@ format="SVG" scale="60"/>
<section xml:id="Concepts"> <section xml:id="Concepts">
<title>Glossary</title> <title>Glossary</title>
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<para> To use the Block Storage API effectively, you should understand several key concepts: </para> <para>To use the Block Storage API effectively, you should understand several key concepts:</para>
<section xml:id="Volume"> <section xml:id="Volume">
<title>Volume</title> <title>Volume</title>
<para>A volume is a detachable block storage device. You can think of it as a USB hard <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> drive. It can only be attached to one instance at a time.</para>
</section> </section>
<section xml:id="Snapshot"> <section xml:id="Snapshot">
<title>Snapshot</title> <title>Snapshot</title>
@ -177,10 +177,10 @@ format="SVG" scale="60"/>
<title>Volume Type</title> <title>Volume Type</title>
<para>The volume type is the type of a block storage volume. You may define whatever types <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 work best for you, such as SATA, SCSCI, SSD, etc. These can be customized or defined by
the OpenStack admin. </para> the OpenStack admin.</para>
<para> You may also define extra_specs associated with your volume types. For instance, you <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 could have a VolumeType=SATA, with extra_specs (RPM=10000, RAID-Level=5) . Extra_specs are
defined and customized by the admin. </para> defined and customized by the admin.</para>
</section> </section>
<section xml:id="Instance"> <section xml:id="Instance">
<title>Instance</title> <title>Instance</title>
@ -215,20 +215,20 @@ format="SVG" scale="60"/>
<chapter xml:id="General_API_Information" xmlns:svg="http://www.w3.org/2000/svg" <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"> xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml">
<title>General API Information</title> <title>General API Information</title>
<!-- <para> The Block Storage API is implemented using a ReSTful <!-- <para>The Block Storage API is implemented using a ReSTful
web service interface. Like other products in the web service interface. Like other products in the
Cloud suite, Block Storage shares a common token-based Cloud suite, Block Storage shares a common token-based
authentication system that allows seamless access between authentication system that allows seamless access between
products and services. </para> products and services.</para>
<note> <note>
<para> All requests to authenticate against and operate the <para>All requests to authenticate against and operate the
service are performed using SSL over HTTP (HTTPS) on TCP port service are performed using SSL over HTTP (HTTPS) on TCP port
443. </para> 443.</para>
</note> </note>
--> -->
<section xml:id="Authentication-d1e647"> <section xml:id="Authentication-d1e647">
<title>Authentication</title> <title>Authentication</title>
<para> You can use <link xlink:href="http://curl.haxx.se/">cURL</link> to try the <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. <orderedlist> authentication process in two steps: get a token; send the token to a service. <orderedlist>
<listitem> <listitem>
<para>Get an authentication token by providing your username and either your API key or <para>Get an authentication token by providing your username and either your API key or
@ -238,11 +238,11 @@ format="SVG" scale="60"/>
<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> <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>
<para> Successful authentication returns a token which you can use as evidence that your <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 identity has already been authenticated. To use the token, pass it to other services
as an <code>X-Auth-Token</code> header. </para> as an <code>X-Auth-Token</code> header.</para>
<para> Authentication also returns a service catalog, listing the endpoints you can use <para>Authentication also returns a service catalog, listing the endpoints you can use
for Cloud services. </para> for Cloud services.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Use the authentication token to send a GET to a service you would like to use. <para>Use the authentication token to send a GET to a service you would like to use.
@ -251,12 +251,12 @@ format="SVG" scale="60"/>
</orderedlist> </orderedlist>
</para> </para>
<para>Authentication tokens are typically valid for 24 hours. Applications should be designed <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> to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.</para>
<important> <important>
<para>If you are programmatically parsing an authentication response, please be aware that <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. 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 You should also be aware that a user's service catalog can include multiple uniquely-named
services which perform similar functions. </para> services which perform similar functions.</para>
</important> </important>
</section> </section>
<section xml:id="Request_Response_Types-d1e903"> <section xml:id="Request_Response_Types-d1e903">
@ -270,7 +270,7 @@ format="SVG" scale="60"/>
default. If conflicting formats are specified using both an <code>Accept</code> header and a default. If conflicting formats are specified using both an <code>Accept</code> header and a
query extension, the query extension takes precedence.</para> query extension, the query extension takes precedence.</para>
<para security="writeronly">Some operations support an Atom representation that can be used to <para security="writeronly">Some operations support an Atom representation that can be used to
efficiently determine when the state of services has changed. </para> efficiently determine when the state of services has changed.</para>
<table rules="all"> <table rules="all">
<caption>Response Formats</caption> <caption>Response Formats</caption>
<?dbfo keep-together="always"?> <?dbfo keep-together="always"?>
@ -333,21 +333,21 @@ format="SVG" scale="60"/>
</section> </section>
<section xml:id="Limits-d1e1208"> <section xml:id="Limits-d1e1208">
<title>Limits</title> <title>Limits</title>
<para> All accounts, by default, have a preconfigured set of thresholds (or limits) to manage <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: 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 <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 are thresholds that are reset after a certain amount of time passes. Absolute limits are
fixed. </para> fixed.</para>
<section xml:id="Rate_Limits-d1e1222" security="writeronly"> <section xml:id="Rate_Limits-d1e1222" security="writeronly">
<title>Rate Limits</title> <title>Rate Limits</title>
<para> Rate limits are specified in terms of both a human-readable wild-card URI and a <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 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 effect after the root URI path. For example, the regular expression ^/v1.0/instances would
match the bolded portion of the following URI: match the bolded portion of the following URI:
https://dfw.blockstorage.api.openstackcloud.com<emphasis role="bold" https://dfw.blockstorage.api.openstackcloud.com<emphasis role="bold"
>/v1.0/instances</emphasis>. </para> >/v1.0/instances</emphasis>.</para>
<para>The following table specifies the default rate limits for all API operations for all <para>The following table specifies the default rate limits for all API operations for all
&GET;, &POST;, &PUT;, and &DELETE; calls for volumes: </para> &GET;, &POST;, &PUT;, and &DELETE; calls for volumes:</para>
<table rules="all"> <table rules="all">
<caption>Default Rate Limits</caption> <caption>Default Rate Limits</caption>
<thead> <thead>
@ -391,12 +391,12 @@ format="SVG" scale="60"/>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<para> Rate limits are applied in order relative to the verb, going from least to most <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 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> 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 <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> 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> header to notify the client when it can attempt to try again.</para>
</section> </section>
<section xml:id="Absolute_Limits-d1e1397"> <section xml:id="Absolute_Limits-d1e1397">
<title>Absolute Limits</title> <title>Absolute Limits</title>
@ -416,7 +416,7 @@ format="SVG" scale="60"/>
<tbody> <tbody>
<tr> <tr>
<td colspan="1">Block Storage</td> <td colspan="1">Block Storage</td>
<td colspan="1">Maximum amount of block storage (in gigabytes) </td> <td colspan="1">Maximum amount of block storage (in gigabytes)</td>
<td colspan="1">1 TB</td> <td colspan="1">1 TB</td>
</tr> </tr>
</tbody> </tbody>
@ -425,8 +425,8 @@ format="SVG" scale="60"/>
</section> </section>
<section xml:id="datetimeformat"> <section xml:id="datetimeformat">
<title>Date/Time Format</title> <title>Date/Time Format</title>
<para> The Block Storage Service uses an ISO-8601 compliant date format for the display and <para>The Block Storage Service uses an ISO-8601 compliant date format for the display and
consumption of date/time values. </para> consumption of date/time values.</para>
<example> <example>
<title>DB Service Date/Time Format</title> <title>DB Service Date/Time Format</title>
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting> <programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
@ -485,9 +485,9 @@ format="SVG" scale="60"/>
<section xml:id="DB_faults"> <section xml:id="DB_faults">
<title>Faults</title> <title>Faults</title>
<para> When an error occurs, the Block Storage Service returns a fault object containing an <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 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> system will return additional information about the fault.</para>
<para>The following table lists possible fault types with their associated error codes and <para>The following table lists possible fault types with their associated error codes and
descriptions.</para> descriptions.</para>
<informaltable rules="all"> <informaltable rules="all">
@ -562,7 +562,7 @@ format="SVG" scale="60"/>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
<para> The following two <code>instanceFault</code> examples show errors when the server has <para>The following two <code>instanceFault</code> examples show errors when the server has
erred or cannot perform the requested operation:</para> erred or cannot perform the requested operation:</para>
<example> <example>
<title>Example instanceFault Response: XML</title> <title>Example instanceFault Response: XML</title>
@ -578,14 +578,14 @@ format="SVG" scale="60"/>
<xi:include href="samples/db-faults-instanceFault.json" parse="text"/> <xi:include href="samples/db-faults-instanceFault.json" parse="text"/>
</programlisting> </programlisting>
</example> </example>
<para> The error code (<code>code</code>) is returned in the body of the response for <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 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 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. 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, 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> 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 <para>The fault's root element (for example, <code>instanceFault</code>) may change depending
on the type of error. </para> on the type of error.</para>
<para><?rax-fo keep-with-next?>The following two <code>badRequest</code> examples show errors <para><?rax-fo keep-with-next?>The following two <code>badRequest</code> examples show errors
when the volume size is invalid:</para> when the volume size is invalid:</para>
<example> <example>
@ -602,7 +602,7 @@ format="SVG" scale="60"/>
<xi:include href="samples/db-faults-badRequest.json" parse="text"/> <xi:include href="samples/db-faults-badRequest.json" parse="text"/>
</programlisting> </programlisting>
</example> </example>
<para> The next two examples show <code>itemNotFound</code> errors:</para> <para>The next two examples show <code>itemNotFound</code> errors:</para>
<example> <example>
<title>Example itemNotFound Fault: XML</title> <title>Example itemNotFound Fault: XML</title>
<?dbfo keep-together="always"?> <?dbfo keep-together="always"?>
@ -749,7 +749,7 @@ Accept: application/json
<td>&GET;</td> <td>&GET;</td>
<td>/volumes</td> <td>/volumes</td>
<td>Lists a summary of all volumes defined in Cinder that are accessible to the tenant <td>Lists a summary of all volumes defined in Cinder that are accessible to the tenant
who submits the request. </td> who submits the request.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -788,7 +788,7 @@ Accept: application/json
<td>&GET;</td> <td>&GET;</td>
<td>/volumes/details</td> <td>/volumes/details</td>
<td>List detailed information of all volumes defined in Cinder that are accessible to <td>List detailed information of all volumes defined in Cinder that are accessible to
the tenant who submits the request. </td> the tenant who submits the request.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -824,7 +824,7 @@ Accept: application/json
<tr> <tr>
<td>&GET;</td> <td>&GET;</td>
<td>/volumes/<parameter>volume-id</parameter></td> <td>/volumes/<parameter>volume-id</parameter></td>
<td>Lists detailed information for the specified volume ID. </td> <td>Lists detailed information for the specified volume ID.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1000,7 +1000,7 @@ The response body will be empty with status code 202.
<td>&GET;</td> <td>&GET;</td>
<td>/snapshots</td> <td>/snapshots</td>
<td>Lists a summary of all snapshots defined in Cinder that are accessible to the <td>Lists a summary of all snapshots defined in Cinder that are accessible to the
tenant who submits the request. </td> tenant who submits the request.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1038,7 +1038,7 @@ Accept: application/json
<td>&GET;</td> <td>&GET;</td>
<td>/snapshots/details</td> <td>/snapshots/details</td>
<td>List detailed information of all snapshots defined in Cinder that are accessible <td>List detailed information of all snapshots defined in Cinder that are accessible
to the tenant who submits the request. </td> to the tenant who submits the request.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1074,7 +1074,7 @@ Accept: application/json
<tr> <tr>
<td>&GET;</td> <td>&GET;</td>
<td>/snapshots/<parameter>snapshot-id</parameter></td> <td>/snapshots/<parameter>snapshot-id</parameter></td>
<td>Lists detailed information for the specified snapshot ID. </td> <td>Lists detailed information for the specified snapshot ID.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>

5
v1/src/samples/os-volume-1.wadl
View File

@ -86,7 +86,6 @@
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="Create Volume"> <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN" title="Create Volume">
<p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">Creates the volume.</p> <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">Creates the volume.</p>
<!-- <!--
The below are examples of how to insert new text into the wadl and have it display. The below are examples of how to insert new text into the wadl and have it display.
Two forms of text are given, Comment to the Reviewer and Straight Text Two forms of text are given, Comment to the Reviewer and Straight Text
@ -167,9 +166,6 @@
as another device on the Next Generation Compute Server. It can as another device on the Next Generation Compute Server. It can
then be partitioned, formatted, and mounted for use on the system. then be partitioned, formatted, and mounted for use on the system.
</p></doc> </p></doc>
</representation> </representation>
</response> </response>
</method> </method>
@ -334,7 +330,6 @@
</doc> </doc>
</param> </param>
<representation mediaType="application/xml"> <representation mediaType="application/xml">
<doc xml:lang="EN"> <doc xml:lang="EN">
<xsdxt:code href="samples/snapshot_create.xml" /> <xsdxt:code href="samples/snapshot_create.xml" />

76
v2/src/openstack-blockstorage-devguide.xml
View File

@ -145,7 +145,7 @@ format="SVG" scale="60"/>
<title>Intended Audience</title> <title>Intended Audience</title>
<para>This guide assists software developers who develop <para>This guide assists software developers who develop
applications by using the &API;. It assumes the reader has a applications by using the &API;. It assumes the reader has a
general understanding of storage and is familiar with: </para> general understanding of storage and is familiar with:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>ReSTful web services</para> <para>ReSTful web services</para>
@ -165,7 +165,7 @@ format="SVG" scale="60"/>
<title>Additional Resources</title> <title>Additional Resources</title>
<para>You can download the latest API-related documents from <para>You can download the latest API-related documents from
<link xlink:href="http://docs.openstack.org/api/" <link xlink:href="http://docs.openstack.org/api/"
>docs.openstack.org/api/</link>. </para> >docs.openstack.org/api/</link>.</para>
<para>This API uses standard HTTP 1.1 response codes as <para>This API uses standard HTTP 1.1 response codes as
documented at: <link documented at: <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
@ -190,7 +190,7 @@ format="SVG" scale="60"/>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist></para>
<para>You interact with Block Storage programmatically through the <para>You interact with Block Storage programmatically through the
Block Storage API as described in this guide. </para> Block Storage API as described in this guide.</para>
<note> <note>
<para><itemizedlist> <para><itemizedlist>
<listitem> <listitem>
@ -217,8 +217,8 @@ format="SVG" scale="60"/>
<section xml:id="Concepts"> <section xml:id="Concepts">
<title>Glossary</title> <title>Glossary</title>
<?dbhtml stop-chunking?> <?dbhtml stop-chunking?>
<para> To use the Block Storage API effectively, you should <para>To use the Block Storage API effectively, you should
understand several key concepts: </para> understand several key concepts:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><emphasis role="bold">Volume</emphasis></para> <para><emphasis role="bold">Volume</emphasis></para>
@ -231,13 +231,13 @@ format="SVG" scale="60"/>
<para>A type of a block storage volume. You can define <para>A type of a block storage volume. You can define
whatever types work best for you, such as SATA, SCSCI, whatever types work best for you, such as SATA, SCSCI,
SSD, etc. These can be customized or defined by the SSD, etc. These can be customized or defined by the
OpenStack admin. </para> OpenStack admin.</para>
<para>You can also define extra_specs associated with your <para>You can also define extra_specs associated with your
volume types. For instance, you could have a volume types. For instance, you could have a
VolumeType=SATA, with extra_specs (RPM=10000, VolumeType=SATA, with extra_specs (RPM=10000,
RAID-Level=5) . Extra_specs are defined and customized by RAID-Level=5) . Extra_specs are defined and customized by
the admin. </para> the admin.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Snapshot</emphasis></para> <para><emphasis role="bold">Snapshot</emphasis></para>
@ -295,11 +295,11 @@ format="SVG" scale="60"/>
<para>The Block Storage API is implemented using a ReSTful web <para>The Block Storage API is implemented using a ReSTful web
service interface. Like other OpenStack projects, Block Storage service interface. Like other OpenStack projects, Block Storage
shares a common token-based authentication system that allows shares a common token-based authentication system that allows
access between products and services. </para> access between products and services.</para>
<note> <note>
<para>All requests to authenticate against and operate the <para>All requests to authenticate against and operate the
service are performed using SSL over HTTP (HTTPS) on TCP port service are performed using SSL over HTTP (HTTPS) on TCP port
443. </para> 443.</para>
</note> </note>
<section xml:id="Authentication-d1e647"> <section xml:id="Authentication-d1e647">
@ -319,28 +319,28 @@ format="SVG" scale="60"/>
<para>Successful authentication returns a token which you <para>Successful authentication returns a token which you
can use as evidence that your identity has already been can use as evidence that your identity has already been
authenticated. To use the token, pass it to other authenticated. To use the token, pass it to other
services as an <code>X-Auth-Token</code> header. </para> services as an <code>X-Auth-Token</code> header.</para>
<para>Authentication also returns a service catalog, <para>Authentication also returns a service catalog,
listing the endpoints you can use for Cloud services. listing the endpoints you can use for Cloud services.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Use the authentication token to send a GET to a <para>Use the authentication token to send a GET to a
service you would like to use. </para> service you would like to use.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
<para>Authentication tokens are typically valid for 24 hours. <para>Authentication tokens are typically valid for 24 hours.
Applications should be designed to re-authenticate after Applications should be designed to re-authenticate after
receiving a 401 (Unauthorized) response from a service receiving a 401 (Unauthorized) response from a service
endpoint. </para> endpoint.</para>
<important> <important>
<para>If you programmatically parse an authentication <para>If you programmatically parse an authentication
response, be aware that service names are stable for the response, be aware that service names are stable for the
life of the particular service and can be used as keys. You life of the particular service and can be used as keys. You
should also be aware that a user's service catalog can should also be aware that a user's service catalog can
include multiple uniquely-named services that perform include multiple uniquely-named services that perform
similar functions. </para> similar functions.</para>
</important> </important>
</section> </section>
<section xml:id="Request_Response_Types-d1e903"> <section xml:id="Request_Response_Types-d1e903">
@ -359,7 +359,7 @@ format="SVG" scale="60"/>
extension takes precedence.</para> extension takes precedence.</para>
<para security="writeronly">Some operations support an Atom <para security="writeronly">Some operations support an Atom
representation that can be used to efficiently determine when representation that can be used to efficiently determine when
the state of services has changed. </para> the state of services has changed.</para>
<table rules="all"> <table rules="all">
<caption>Response Formats</caption> <caption>Response Formats</caption>
<?dbfo keep-together="always"?> <?dbfo keep-together="always"?>
@ -427,20 +427,20 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<firstterm>rate limits</firstterm> and <firstterm>absolute <firstterm>rate limits</firstterm> and <firstterm>absolute
limits</firstterm>. Rate limits are thresholds that are limits</firstterm>. Rate limits are thresholds that are
reset after a certain amount of time passes. Absolute limits reset after a certain amount of time passes. Absolute limits
are fixed. </para> are fixed.</para>
<section xml:id="Rate_Limits-d1e1222" security="writeronly"> <section xml:id="Rate_Limits-d1e1222" security="writeronly">
<title>Rate Limits</title> <title>Rate Limits</title>
<para> Rate limits are specified in terms of both a <para>Rate limits are specified in terms of both a
human-readable wild-card URI and a machine-processable human-readable wild-card URI and a machine-processable
regular expression. The regular expression boundary matcher regular expression. The regular expression boundary matcher
'^' takes effect after the root URI path. For example, the '^' takes effect after the root URI path. For example, the
regular expression ^/v1.0/instances would match the bolded regular expression ^/v1.0/instances would match the bolded
portion of the following URI: portion of the following URI:
https://dfw.blockstorage.api.openstackcloud.com<emphasis https://dfw.blockstorage.api.openstackcloud.com<emphasis
role="bold">/v1.0/instances</emphasis>. </para> role="bold">/v1.0/instances</emphasis>.</para>
<para>The following table specifies the default rate limits <para>The following table specifies the default rate limits
for all API operations for all &GET;, &POST;, &PUT;, and for all API operations for all &GET;, &POST;, &PUT;, and
&DELETE; calls for volumes: </para> &DELETE; calls for volumes:</para>
<table rules="all"> <table rules="all">
<caption>Default Rate Limits</caption> <caption>Default Rate Limits</caption>
<thead> <thead>
@ -484,15 +484,15 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
</tr> </tr>
</tbody> </tbody>
</table> </table>
<para> Rate limits are applied in order relative to the verb, <para>Rate limits are applied in order relative to the verb,
going from least to most specific. For example, although the going from least to most specific. For example, although the
threshold for &POST; to /v1.0/* is 10 per minute, one cannot 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> &POST; to /v1.0/* more than 50 times within a single day.</para>
<para> If you exceed the thresholds established for your <para>If you exceed the thresholds established for your
account, a <errorcode>413 (Rate Control)</errorcode> HTTP account, a <errorcode>413 (Rate Control)</errorcode> HTTP
response will be returned with a <code>Retry-After</code> response will be returned with a <code>Retry-After</code>
header to notify the client when it can attempt to try header to notify the client when it can attempt to try
again. </para> again.</para>
</section> </section>
<section xml:id="Absolute_Limits-d1e1397"> <section xml:id="Absolute_Limits-d1e1397">
<title>Absolute Limits</title> <title>Absolute Limits</title>
@ -512,7 +512,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<tbody> <tbody>
<tr> <tr>
<td colspan="1">Block Storage</td> <td colspan="1">Block Storage</td>
<td colspan="1">Maximum amount of block storage (in GBs) </td> <td colspan="1">Maximum amount of block storage (in GBs)</td>
<td colspan="1">1 TB</td> <td colspan="1">1 TB</td>
</tr> </tr>
</tbody> </tbody>
@ -522,7 +522,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<section xml:id="datetimeformat"> <section xml:id="datetimeformat">
<title>Date/Time Format</title> <title>Date/Time Format</title>
<para>The Block Storage Service uses an ISO-8601 compliant date <para>The Block Storage Service uses an ISO-8601 compliant date
format for the display and consumption of date/time values. </para> format for the display and consumption of date/time values.</para>
<example> <example>
<title>DB Service Date/Time Format</title> <title>DB Service Date/Time Format</title>
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting> <programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
@ -582,10 +582,10 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
</section> </section>
<section xml:id="DB_faults"> <section xml:id="DB_faults">
<title>Faults</title> <title>Faults</title>
<para> When an error occurs, the Block Storage Service returns a <para>When an error occurs, the Block Storage Service returns a
fault object containing an HTTP error response code that fault object containing an HTTP error response code that
denotes the type of error. In the body of the response, the denotes the type of error. In the body of the response, the
system will return additional information about the fault. </para> system will return additional information about the fault.</para>
<para>The following table lists possible fault types with their <para>The following table lists possible fault types with their
associated error codes and descriptions.</para> associated error codes and descriptions.</para>
<informaltable rules="all" width="100%"> <informaltable rules="all" width="100%">
@ -693,7 +693,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
experience of the end user.</para> experience of the end user.</para>
<para>The fault's root element (for example, <para>The fault's root element (for example,
<code>instanceFault</code>) may change depending on the type <code>instanceFault</code>) may change depending on the type
of error. </para> of error.</para>
<para><?rax-fo keep-with-next?>The following two <para><?rax-fo keep-with-next?>The following two
<code>badRequest</code> examples show errors when the volume <code>badRequest</code> examples show errors when the volume
size is invalid:</para> size is invalid:</para>
@ -709,7 +709,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<?dbfo keep-together="always"?> <?dbfo keep-together="always"?>
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting> <programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
</example> </example>
<para> The next two examples show <code>itemNotFound</code> <para>The next two examples show <code>itemNotFound</code>
errors:</para> errors:</para>
<example> <example>
<title>Example itemNotFound Fault: XML</title> <title>Example itemNotFound Fault: XML</title>
@ -871,7 +871,7 @@ Accept: application/json</literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/volumes</td> <td>/volumes</td>
<td>Lists volumes defined in Block Storage that the <td>Lists volumes defined in Block Storage that the
tenant who submits the request can access. </td> tenant who submits the request can access.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -940,7 +940,7 @@ Accept: application/json </literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/volumes/<parameter>volume-id</parameter></td> <td>/volumes/<parameter>volume-id</parameter></td>
<td>Lists detailed information for the specified volume <td>Lists detailed information for the specified volume
ID. </td> ID.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1104,7 +1104,7 @@ Accept: application/json</literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/snapshots</td> <td>/snapshots</td>
<td>Lists snapshots defined in Block Storage that the <td>Lists snapshots defined in Block Storage that the
tenant who submits the request can access. </td> tenant who submits the request can access.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1139,7 +1139,7 @@ Accept: application/json </literallayout>
<td>/snapshots/details</td> <td>/snapshots/details</td>
<td>Lists detailed information for snapshots defined in <td>Lists detailed information for snapshots defined in
Block Storage that the tenant who submits the request Block Storage that the tenant who submits the request
can access. </td> can access.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1173,7 +1173,7 @@ Accept: application/json </literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/snapshots/<parameter>snapshot-id</parameter></td> <td>/snapshots/<parameter>snapshot-id</parameter></td>
<td>Lists detailed information for a specified snapshot <td>Lists detailed information for a specified snapshot
ID. </td> ID.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1328,7 +1328,7 @@ Accept: application/json </literallayout>
<section xml:id="Extensions"> <section xml:id="Extensions">
<title>Extensions</title> <title>Extensions</title>
<para>The Block Storage API is extensible. Extensions are <para>The Block Storage API is extensible. Extensions are
add-ons to the API that enable new features. </para> add-ons to the API that enable new features.</para>
<section xml:id="Backups"> <section xml:id="Backups">
<title>Backups</title> <title>Backups</title>
<para>A backup is a full copy of a volume stored in an <para>A backup is a full copy of a volume stored in an
@ -1338,7 +1338,7 @@ Accept: application/json </literallayout>
the same volume that the backup was originally taken from, the same volume that the backup was originally taken from,
or to a new volume. Backup and restore operations can only or to a new volume. Backup and restore operations can only
be carried out on volumes which are in an unattached and be carried out on volumes which are in an unattached and
available state. </para> available state.</para>
<para><?rax-fo keep-with-next?>When making an API call to <para><?rax-fo keep-with-next?>When making an API call to
create, list, or delete backup(s), the following status create, list, or delete backup(s), the following status
values are possible:</para> values are possible:</para>
@ -1470,7 +1470,7 @@ Accept: application/json </literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/backups</td> <td>/backups</td>
<td>Lists backups defined in Block Storage that the <td>Lists backups defined in Block Storage that the
tenant who submits the request can access. </td> tenant who submits the request can access.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1505,7 +1505,7 @@ Accept: application/json </literallayout>
<td>/backups/details</td> <td>/backups/details</td>
<td>Lists detailed information for backups defined in <td>Lists detailed information for backups defined in
Block Storage that the tenant who submits the Block Storage that the tenant who submits the
request can access. </td> request can access.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>
@ -1539,7 +1539,7 @@ Accept: application/json </literallayout>
<td>&GET;</td> <td>&GET;</td>
<td>/backups/<parameter>backup-id</parameter></td> <td>/backups/<parameter>backup-id</parameter></td>
<td>Lists detailed information for a specified backup <td>Lists detailed information for a specified backup
ID. </td> ID.</td>
</tr> </tr>
</tbody> </tbody>
</informaltable> </informaltable>