openstack-attic/volume-api
Code Issues Proposed changes

Change to add response status codes for Cinder

Browse Source 
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
This commit is contained in:
vilobhmm 2014-06-04 22:08:24 +00:00 committed by Diane Fleming
parent 9c172cf523
commit d813475bc0
4 changed files with 113 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
pom.xml
View File

@ -39,7 +39,7 @@
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>2.0.2</version>
<version>2.0.4</version>
</plugin>
</plugins>
</build>

28
v1/bk_blockstorage_api_ref_v1.xml
View File

@ -68,12 +68,23 @@ format="SVG" scale="60"/>
<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>Updating v1 documentation; .</para>
<para>Updated v1 documentation.</para>
</listitem>
</itemizedlist>
</revdescription>
@ -83,7 +94,7 @@ format="SVG" scale="60"/>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Edits to initial version; .</para>
<para>Edits to initial version.</para>
</listitem>
</itemizedlist>
</revdescription>
@ -360,6 +371,7 @@ format="SVG" scale="60"/>
</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
@ -628,9 +640,7 @@ format="SVG" scale="60"/>
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>
<programlisting language="xml"><xi:include href="samples/db-faults-instanceFault.xml" parse="text"/></programlisting>
</example>
<example>
<title>Example fault: JSON response</title>
@ -638,9 +648,7 @@ Date: Mon, 28 Nov 2011 18:19:37 GMT</computeroutput></screen>
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>
<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>
@ -656,7 +664,7 @@ Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
of error.</para>
<para><?rax-fo keep-with-next?>The following
<code>badRequest</code> examples show errors when the volume
size is not valie:</para>
size is not valid:</para>
<example>
<title>Example badRequest fault and volume size errors: XML
request</title>
@ -675,7 +683,7 @@ Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
</example>
<para>The next two examples show <code>itemNotFound</code>
<para>The following examples show <code>itemNotFound</code>
errors:</para>
<example>
<title>Example itemNotFound fault: XML response</title>

18
v2/bk_blockstorage_api_ref_v2.xml
View File

@ -63,14 +63,25 @@ format="SVG" scale="60"/>
Programming Interface (<abbrev>API</abbrev>).</para>
</abstract>
<revhistory>
<revision>
<date>2014-06-17</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Added common response status codes returned by
Block Storage.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<date>2014-05-01</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Add Block Storage extensions to the API operations
chapter.</para>
<para>Added Block Storage extensions to the API
operations chapter.</para>
</listitem>
</itemizedlist>
</revdescription>
@ -400,7 +411,7 @@ Content-Length: 187
Content-Type: application/xml
X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;?xml version='1.0' encoding='UTF-7'?&gt;
&lt;volume_types&gt;
&lt;volume_type id="1" name="SATA"&gt;
&lt;extra_specs/&gt;
@ -411,6 +422,7 @@ X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
&lt;/volume_types&gt;</literallayout>
</example>
</section>
<xi:include href="section_http_status_codes.xml"/>
<section xml:id="Limits-d1e1208">
<title>Limits</title>
<para>All accounts, by default, have a preconfigured set of

79
v2/section_http_status_codes.xml Normal file
View File

@ -0,0 +1,79 @@
<?xml version="1.0" encoding="UTF-8"?>
<section 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="Response_status_codes-d1e904">
<title>HTTP response status codes</title>
<para>When an error occurs, Block Storage returns an HTTP error
response code that denotes the type of error. Some errors
returns a response body, which returns additional information
about the error.</para>
<para>The following table describes the possible status
codes:</para>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="40%"/>
<col width="40%"/>
<thead>
<tr>
<th>Response status code</th>
<th>Description</th>
<th>Response body?</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Generic successful response.</td>
<td>Yes</td>
</tr>
<tr>
<td>201</td>
<td>Entity created.</td>
<td>Yes. Expect a location header and a response
body.</td>
</tr>
<tr>
<td>204</td>
<td>Successful response without body.</td>
<td>No</td>
</tr>
<tr>
<td>301</td>
<td>Redirection.</td>
<td>Yes</td>
</tr>
<tr>
<td>400</td>
<td>Invalid request (syntax, value, and so on).</td>
<td>Yes</td>
</tr>
<tr>
<td>401</td>
<td>Unauthenticated client.</td>
<td>Yes</td>
</tr>
<tr>
<td>403</td>
<td>Authenticated client unable to perform
action.</td>
<td>Yes</td>
</tr>
<tr>
<td>409</td>
<td>Action cannot be completed due to situation that
is possibly permanent.</td>
<td>Yes</td>
</tr>
<tr>
<td>415</td>
<td>Unsupported type.</td>
<td>Yes, with type details.</td>
</tr>
</tbody>
</informaltable>
</section>