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

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

@ -18,12 +18,12 @@
</param> -->
<?rax start-sections?>
<resource id="volumes" path="volumes">
<doc title="Volumes"/>
<doc title="Volumes"/>
<method href="#createVolume" />
<method href="#getVolumesSimple" />
<resource path="detail" id="detail">
<!-- as of 7-25-12, this is same as non-detailed
<!-- as of 7-25-12, this is same as non-detailed
<method href="#getVolumesDetail" /> -->
</resource>
@ -33,13 +33,13 @@
The unique identifier of an existing Volume.
</p></doc>
</param>
<method href="#getVolume" />
<method href="#deleteVolume" />
</resource>
</resource>
<resource id="volume_types" path="/types">
<doc title="Volume types"/>
<method href="#getVolumeTypes" />
@ -56,12 +56,12 @@
</resource>
<resource id="snapshots" path="snapshots">
<doc title="Snapshots"/>
<doc title="Snapshots"/>
<method href="#createSnapshot" />
<method href="#getSnapshotsSimple" />
<resource path="detail" id="snapshot_detail">
<!-- as of 7-25-12, this is same as non-detailed
<!-- as of 7-25-12, this is same as non-detailed
<method href="#getSnapshotsDetail" /> -->
</resource>
@ -85,17 +85,17 @@
<method name="POST" id="createVolume">
<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>
<!--
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
<p>
<remark xmlns="http://docbook.org/ns/docbook" security="reviewer">Reviewer - Here is my question!</remark>
</p>
<p xmlns="http://www.w3.org/1999/xhtml">Create a Volume - hey! this is old text.
<p xmlns="http://www.w3.org/1999/xhtml">Create a Volume - hey! this is old text.
The below example creates a volume called vol-001.</p>
-->
-->
<doc><p xmlns="http://www.w3.org/1999/xhtml">
The below example creates a SATA volume called "vol-001" that has a size of 30 GB.
</p></doc>
@ -118,16 +118,16 @@
</param>
<param name="display_name" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
The name of the volume.
The name of the volume.
</p></doc>
</param>
<param name="metadata" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Key and value metadata pairs defined by the admin.
Key and value metadata pairs defined by the admin.
</p></doc>
</param>
<param name="snapshot_id" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
The optional snapshot from which to create a volume.
@ -139,12 +139,12 @@
then the default, SATA, is used.
</p></doc>
</param>
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/volume_create.xml" />
</doc>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
@ -164,14 +164,12 @@
<xsdxt:code href="samples/volume_show.json" />
</doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Note that you use the <code>os-volume_attachments</code> API call
(/servers/{server_id}/os-volume_attachments) to attach
the new volume to your Server (with
the specified {server_id}).
Note that you use the <code>os-volume_attachments</code> API call
(/servers/{server_id}/os-volume_attachments) to attach
the new volume to your Server (with
the specified {server_id}).
</p></doc>
</representation>
</response>
</method>
@ -203,9 +201,9 @@
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/volume_list_simple.xml" />
</doc>
</representation>
<representation mediaType="application/json">
@ -259,9 +257,9 @@
<xsdxt:code href="samples/volume_type_list.json" />
</doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Note that two storage types are currently supported: SATA
and SSD. SATA is the standard performance storage option
and SSD is the high performance option.
Note that two storage types are currently supported: SATA
and SSD. SATA is the standard performance storage option
and SSD is the high performance option.
</p></doc>
</representation>
</response>
@ -272,7 +270,7 @@
<p xmlns="http://www.w3.org/1999/xhtml">Request a single Volume Type.</p>
</wadl:doc>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
@ -288,11 +286,11 @@
</method>
<method name="POST" id="createSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Create Snapshot">
<p class="shortdesc" xmlns="http://www.w3.org/1999/xhtml">Create a Snapshot.</p>
</wadl:doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Creating a snapshot makes a point-in-time copy of the
volume. All writes to the volume should be flushed <i>before</i>
@ -301,7 +299,7 @@
Snapshots are incremental, so each time you create a new snapshot, you are
appending the incremental changes for the new snapshot to the previous
one. The previous snapshot is still available. Note that you can
create a new volume from the snapshot if desired.
create a new volume from the snapshot if desired.
</p></doc>
<request>
<param name="snapshot" style="query" type="string" required="true">
@ -318,11 +316,11 @@
</param>
<param name="force" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
[True/False] Indicate whether to snapshot, even if the volume is attached.
[True/False] Indicate whether to snapshot, even if the volume is attached.
Default==False.
</p>
</doc>
</param>
</param>
<param name="display_name" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Name of the snapshot. Default==None.
@ -335,8 +333,7 @@
</p>
</doc>
</param>
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/snapshot_create.xml" />
@ -363,7 +360,7 @@
</method>
<method name="GET" id="getSnapshotsSimple">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="List Snapshots">
<p xmlns="http://www.w3.org/1999/xhtml">
View a list of simple Snapshot entities.
@ -384,7 +381,7 @@
</method>
<method name="GET" id="getSnapshotsDetail">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="List Snapshots (Detailed)">
<p xmlns="http://www.w3.org/1999/xhtml">
View a list of detailed Snapshot entities.
@ -406,7 +403,7 @@
<method name="GET" id="getSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Show Snapshot">
<p xmlns="http://www.w3.org/1999/xhtml">
View all information about a single Snapshot.
@ -427,7 +424,7 @@
</method>
<method name="DELETE" id="deleteSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Delete Snapshot">
<p xmlns="http://www.w3.org/1999/xhtml">Delete a single Snapshot.</p>
</wadl:doc>

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

@ -55,7 +55,7 @@ format="SVG" scale="60"/>
</legalnotice>
<abstract>
<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>
<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">
@ -101,7 +101,7 @@ format="SVG" scale="60"/>
<title>Intended Audience</title>
<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
familiar with: </para>
familiar with:</para>
<itemizedlist spacing="compact">
<listitem>
<para>ReSTful web services</para>
@ -120,10 +120,10 @@ format="SVG" scale="60"/>
<section xml:id="Additional_Resources-d1e532">
<title>Additional 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>
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>
>www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.</para>
</section>
</preface>
<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
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>
applications.</para>
<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>
<listitem>
<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">
<title>Glossary</title>
<?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">
<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>
drive. It can only be attached to one instance at a time.</para>
</section>
<section xml:id="Snapshot">
<title>Snapshot</title>
@ -177,10 +177,10 @@ format="SVG" scale="60"/>
<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
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>
defined and customized by the admin.</para>
</section>
<section xml:id="Instance">
<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"
xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml">
<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
Cloud suite, Block Storage shares a common token-based
authentication system that allows seamless access between
products and services. </para>
products and services.</para>
<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
443. </para>
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
<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>
<listitem>
<para>Get an authentication token by providing your username and either your API key or
@ -238,11 +238,11 @@ format="SVG" scale="60"/>
<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
<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>
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.
@ -251,12 +251,12 @@ format="SVG" scale="60"/>
</orderedlist>
</para>
<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>
<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>
services which perform similar functions.</para>
</important>
</section>
<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
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>
efficiently determine when the state of services has changed.</para>
<table rules="all">
<caption>Response Formats</caption>
<?dbfo keep-together="always"?>
@ -333,21 +333,21 @@ format="SVG" scale="60"/>
</section>
<section xml:id="Limits-d1e1208">
<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:
<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>
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
<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>
>/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>
&GET;, &POST;, &PUT;, and &DELETE; calls for volumes:</para>
<table rules="all">
<caption>Default Rate Limits</caption>
<thead>
@ -391,12 +391,12 @@ format="SVG" scale="60"/>
</tr>
</tbody>
</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
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
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>
header to notify the client when it can attempt to try again.</para>
</section>
<section xml:id="Absolute_Limits-d1e1397">
<title>Absolute Limits</title>
@ -416,7 +416,7 @@ format="SVG" scale="60"/>
<tbody>
<tr>
<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>
</tr>
</tbody>
@ -425,8 +425,8 @@ format="SVG" scale="60"/>
</section>
<section xml:id="datetimeformat">
<title>Date/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>
<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/Time Format</title>
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
@ -485,9 +485,9 @@ format="SVG" scale="60"/>
<section xml:id="DB_faults">
<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
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
descriptions.</para>
<informaltable rules="all">
@ -562,7 +562,7 @@ format="SVG" scale="60"/>
</tr>
</tbody>
</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>
<example>
<title>Example instanceFault Response: XML</title>
@ -578,14 +578,14 @@ format="SVG" scale="60"/>
<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
<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>
on the type of error.</para>
<para><?rax-fo keep-with-next?>The following two <code>badRequest</code> examples show errors
when the volume size is invalid:</para>
<example>
@ -602,7 +602,7 @@ format="SVG" scale="60"/>
<xi:include href="samples/db-faults-badRequest.json" parse="text"/>
</programlisting>
</example>
<para> The next two examples show <code>itemNotFound</code> errors:</para>
<para>The next two examples show <code>itemNotFound</code> errors:</para>
<example>
<title>Example itemNotFound Fault: XML</title>
<?dbfo keep-together="always"?>
@ -749,7 +749,7 @@ Accept: application/json
<td>&GET;</td>
<td>/volumes</td>
<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>
</tbody>
</informaltable>
@ -788,7 +788,7 @@ Accept: application/json
<td>&GET;</td>
<td>/volumes/details</td>
<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>
</tbody>
</informaltable>
@ -824,7 +824,7 @@ Accept: application/json
<tr>
<td>&GET;</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>
</tbody>
</informaltable>
@ -1000,7 +1000,7 @@ The response body will be empty with status code 202.
<td>&GET;</td>
<td>/snapshots</td>
<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>
</tbody>
</informaltable>
@ -1038,7 +1038,7 @@ Accept: application/json
<td>&GET;</td>
<td>/snapshots/details</td>
<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>
</tbody>
</informaltable>
@ -1074,7 +1074,7 @@ Accept: application/json
<tr>
<td>&GET;</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>
</tbody>
</informaltable>

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

@ -18,12 +18,12 @@
</param> -->
<?rax start-sections?>
<resource id="volumes" path="volumes">
<doc title="Volumes"/>
<doc title="Volumes"/>
<method href="#createVolume" />
<method href="#getVolumesSimple" />
<resource path="detail" id="detail">
<!-- as of 7-25-12, this is same as non-detailed
<!-- as of 7-25-12, this is same as non-detailed
<method href="#getVolumesDetail" /> -->
</resource>
@ -33,13 +33,13 @@
The unique identifier of an existing Volume.
</p></doc>
</param>
<method href="#getVolume" />
<method href="#deleteVolume" />
</resource>
</resource>
<resource id="volume_types" path="/types">
<doc title="Volume types"/>
<method href="#getVolumeTypes" />
@ -61,7 +61,7 @@
<method href="#getSnapshotsSimple" />
<resource path="detail" id="snapshot_detail">
<!-- as of 7-25-12, this is same as non-detailed
<!-- as of 7-25-12, this is same as non-detailed
<method href="#getSnapshotsDetail" /> -->
</resource>
@ -85,17 +85,16 @@
<method name="POST" id="createVolume">
<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>
<!--
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
<p>
<remark xmlns="http://docbook.org/ns/docbook" security="reviewer">Reviewer - Here is my question!</remark>
</p>
<p xmlns="http://www.w3.org/1999/xhtml">Create a Volume - hey! this is old text.
<p xmlns="http://www.w3.org/1999/xhtml">Create a Volume - hey! this is old text.
The below example creates a volume called vol-001.</p>
-->
-->
<doc><p xmlns="http://www.w3.org/1999/xhtml">
The below example creates a SATA volume called "vol-001" that has a size of 30 GB.
</p></doc>
@ -118,7 +117,7 @@
</param>
<param name="display_name" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
The name of the volume.
The name of the volume.
</p></doc>
</param>
<param name="snampshot_id" style="query" type="string" required="false">
@ -132,12 +131,12 @@
then the default, SATA, is used.
</p></doc>
</param>
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/volume_create.xml" />
</doc>
</doc>
</representation>
<representation mediaType="application/json">
<doc xml:lang="EN">
@ -157,19 +156,16 @@
<xsdxt:code href="samples/volume_show.json" />
</doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Note that you use the <code>os-volume_attachments</code> API call
(/servers/{server_id}/os-volume_attachments) to attach
the new volume to your Next Generation Compute Server (with
the specified {server_id}).
Refer to the <i>Next Generation Compute Servers Developer Guide</i>
at <a href="docs.rackspace.com">docs.rackspace.com</a> for details
of the call. Once the volume is attached, the new volume will appear
as another device on the Next Generation Compute Server. It can
then be partitioned, formatted, and mounted for use on the system.
Note that you use the <code>os-volume_attachments</code> API call
(/servers/{server_id}/os-volume_attachments) to attach
the new volume to your Next Generation Compute Server (with
the specified {server_id}).
Refer to the <i>Next Generation Compute Servers Developer Guide</i>
at <a href="docs.rackspace.com">docs.rackspace.com</a> for details
of the call. Once the volume is attached, the new volume will appear
as another device on the Next Generation Compute Server. It can
then be partitioned, formatted, and mounted for use on the system.
</p></doc>
</representation>
</response>
</method>
@ -201,9 +197,9 @@
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/volume_list_simple.xml" />
</doc>
</representation>
<representation mediaType="application/json">
@ -257,9 +253,9 @@
<xsdxt:code href="samples/volume_type_list.json" />
</doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Note that two storage types are currently supported: SATA
and SSD. SATA is the standard performance storage option
and SSD is the high performance option.
Note that two storage types are currently supported: SATA
and SSD. SATA is the standard performance storage option
and SSD is the high performance option.
</p></doc>
</representation>
</response>
@ -270,7 +266,7 @@
<p xmlns="http://www.w3.org/1999/xhtml">Request a single Volume Type.</p>
</wadl:doc>
<response status="200">
<representation mediaType="application/xml">
<doc xml:lang="EN">
@ -286,11 +282,11 @@
</method>
<method name="POST" id="createSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Create Snapshot">
<p class="shortdesc" xmlns="http://www.w3.org/1999/xhtml">Create a Snapshot.</p>
</wadl:doc>
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Creating a snapshot makes a point-in-time copy of the
volume. All writes to the volume should be flushed <i>before</i>
@ -299,7 +295,7 @@
Snapshots are incremental, so each time you create a new snapshot, you are
appending the incremental changes for the new snapshot to the previous
one. The previous snapshot is still available. Note that you can
create a new volume from the snapshot if desired.
create a new volume from the snapshot if desired.
</p></doc>
<request>
<param name="snapshot" style="query" type="string" required="true">
@ -316,11 +312,11 @@
</param>
<param name="force" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
[True/False] Indicate whether to snapshot, even if the volume is attached.
[True/False] Indicate whether to snapshot, even if the volume is attached.
Default==False.
</p>
</doc>
</param>
</param>
<param name="display_name" style="query" type="string" required="false">
<doc><p xmlns="http://www.w3.org/1999/xhtml">
Name of the snapshot. Default==None.
@ -333,8 +329,7 @@
</p>
</doc>
</param>
<representation mediaType="application/xml">
<doc xml:lang="EN">
<xsdxt:code href="samples/snapshot_create.xml" />
@ -361,7 +356,7 @@
</method>
<method name="GET" id="getSnapshotsSimple">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="List Snapshots">
<p xmlns="http://www.w3.org/1999/xhtml">
View a list of simple Snapshot entities.
@ -382,7 +377,7 @@
</method>
<method name="GET" id="getSnapshotsDetail">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="List Snapshots (Detailed)">
<p xmlns="http://www.w3.org/1999/xhtml">
View a list of detailed Snapshot entities.
@ -404,7 +399,7 @@
<method name="GET" id="getSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Show Snapshot">
<p xmlns="http://www.w3.org/1999/xhtml">
View all information about a single Snapshot.
@ -425,7 +420,7 @@
</method>
<method name="DELETE" id="deleteSnapshot">
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
<wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="E"
title="Delete Snapshot">
<p xmlns="http://www.w3.org/1999/xhtml">Delete a single Snapshot.</p>
</wadl:doc>

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

@ -145,7 +145,7 @@ format="SVG" scale="60"/>
<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>
general understanding of storage and is familiar with:</para>
<itemizedlist spacing="compact">
<listitem>
<para>ReSTful web services</para>
@ -165,7 +165,7 @@ format="SVG" scale="60"/>
<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>
>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"
@ -190,7 +190,7 @@ format="SVG" scale="60"/>
</listitem>
</itemizedlist></para>
<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>
<para><itemizedlist>
<listitem>
@ -217,8 +217,8 @@ format="SVG" scale="60"/>
<section xml:id="Concepts">
<title>Glossary</title>
<?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>
<itemizedlist>
<listitem>
<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
whatever types work best for you, such as SATA, SCSCI,
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
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>
the admin.</para>
</listitem>
<listitem>
<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
service interface. Like other OpenStack projects, Block Storage
shares a common token-based authentication system that allows
access between products and services. </para>
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>
443.</para>
</note>
<section xml:id="Authentication-d1e647">
@ -319,28 +319,28 @@ format="SVG" scale="60"/>
<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>
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>
service you would like to use.</para>
</listitem>
</orderedlist>
</para>
<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>
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>
similar functions.</para>
</important>
</section>
<section xml:id="Request_Response_Types-d1e903">
@ -359,7 +359,7 @@ format="SVG" scale="60"/>
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>
the state of services has changed.</para>
<table rules="all">
<caption>Response Formats</caption>
<?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
limits</firstterm>. Rate limits are thresholds that are
reset after a certain amount of time passes. Absolute limits
are fixed. </para>
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
<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>
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>
&DELETE; calls for volumes:</para>
<table rules="all">
<caption>Default Rate Limits</caption>
<thead>
@ -484,15 +484,15 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
</tr>
</tbody>
</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
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
&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>
again.</para>
</section>
<section xml:id="Absolute_Limits-d1e1397">
<title>Absolute Limits</title>
@ -512,7 +512,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<tbody>
<tr>
<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>
</tr>
</tbody>
@ -522,7 +522,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<section xml:id="datetimeformat">
<title>Date/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>
format for the display and consumption of date/time values.</para>
<example>
<title>DB Service Date/Time Format</title>
<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 xml:id="DB_faults">
<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
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 descriptions.</para>
<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>
<para>The fault's root element (for example,
<code>instanceFault</code>) may change depending on the type
of error. </para>
of error.</para>
<para><?rax-fo keep-with-next?>The following two
<code>badRequest</code> examples show errors when the volume
size is invalid:</para>
@ -709,7 +709,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<?dbfo keep-together="always"?>
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
</example>
<para> The next two examples show <code>itemNotFound</code>
<para>The next two examples show <code>itemNotFound</code>
errors:</para>
<example>
<title>Example itemNotFound Fault: XML</title>
@ -871,7 +871,7 @@ Accept: application/json</literallayout>
<td>&GET;</td>
<td>/volumes</td>
<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>
</tbody>
</informaltable>
@ -940,7 +940,7 @@ Accept: application/json </literallayout>
<td>&GET;</td>
<td>/volumes/<parameter>volume-id</parameter></td>
<td>Lists detailed information for the specified volume
ID. </td>
ID.</td>
</tr>
</tbody>
</informaltable>
@ -1104,7 +1104,7 @@ Accept: application/json</literallayout>
<td>&GET;</td>
<td>/snapshots</td>
<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>
</tbody>
</informaltable>
@ -1139,7 +1139,7 @@ Accept: application/json </literallayout>
<td>/snapshots/details</td>
<td>Lists detailed information for snapshots defined in
Block Storage that the tenant who submits the request
can access. </td>
can access.</td>
</tr>
</tbody>
</informaltable>
@ -1173,7 +1173,7 @@ Accept: application/json </literallayout>
<td>&GET;</td>
<td>/snapshots/<parameter>snapshot-id</parameter></td>
<td>Lists detailed information for a specified snapshot
ID. </td>
ID.</td>
</tr>
</tbody>
</informaltable>
@ -1328,7 +1328,7 @@ Accept: application/json </literallayout>
<section xml:id="Extensions">
<title>Extensions</title>
<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">
<title>Backups</title>
<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,
or to a new volume. Backup and restore operations can only
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
create, list, or delete backup(s), the following status
values are possible:</para>
@ -1470,7 +1470,7 @@ Accept: application/json </literallayout>
<td>&GET;</td>
<td>/backups</td>
<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>
</tbody>
</informaltable>
@ -1505,7 +1505,7 @@ Accept: application/json </literallayout>
<td>/backups/details</td>
<td>Lists detailed information for backups defined in
Block Storage that the tenant who submits the
request can access. </td>
request can access.</td>
</tr>
</tbody>
</informaltable>
@ -1539,7 +1539,7 @@ Accept: application/json </literallayout>
<td>&GET;</td>
<td>/backups/<parameter>backup-id</parameter></td>
<td>Lists detailed information for a specified backup
ID. </td>
ID.</td>
</tr>
</tbody>
</informaltable>

4
v2/src/samples/volume_list_simple_response.xml
View File

@ -1,6 +1,6 @@
<?xml version='1.0' encoding='UTF-8'?>
<volumes
xmlns:atom="http://www.w3.org/2005/Atom"
<volumes
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content">
<volume name="vol-004" id="45baf976-c20a-4894-a7c3-c94b7376bf55">
<attachments/>