From d813475bc0df48007b32bd827775e05b8fc7f026 Mon Sep 17 00:00:00 2001
From: vilobhmm <vilobhmm@yahoo-inc.com>
Date: Wed, 4 Jun 2014 22:08:24 +0000
Subject: [PATCH] Change to add response status codes for Cinder

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
---
 pom.xml                           |  2 +-
 v1/bk_blockstorage_api_ref_v1.xml | 28 +++++++----
 v2/bk_blockstorage_api_ref_v2.xml | 18 +++++--
 v2/section_http_status_codes.xml  | 79 +++++++++++++++++++++++++++++++
 4 files changed, 113 insertions(+), 14 deletions(-)
 create mode 100644 v2/section_http_status_codes.xml

diff --git a/pom.xml b/pom.xml
index fad1045..4498ff5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -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>
diff --git a/v1/bk_blockstorage_api_ref_v1.xml b/v1/bk_blockstorage_api_ref_v1.xml
index 7d9c3f0..e2b9b60 100644
--- a/v1/bk_blockstorage_api_ref_v1.xml
+++ b/v1/bk_blockstorage_api_ref_v1.xml
@@ -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>
diff --git a/v2/bk_blockstorage_api_ref_v2.xml b/v2/bk_blockstorage_api_ref_v2.xml
index b640307..47cea4b 100644
--- a/v2/bk_blockstorage_api_ref_v2.xml
+++ b/v2/bk_blockstorage_api_ref_v2.xml
@@ -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
diff --git a/v2/section_http_status_codes.xml b/v2/section_http_status_codes.xml
new file mode 100644
index 0000000..84f2abc
--- /dev/null
+++ b/v2/section_http_status_codes.xml
@@ -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>