Add note about 416 return code for overtaxed ranged GET requests

Change-Id: I4eda8f1c22ba12863340f8050ecb18d9ce04cd13
Closes-Bug: #1373732

api-ref/src/docbkx/ch_objectstorage-v1.xml

@@ -61,6 +61,27 @@ Accept-Ranges: bytes</programlisting>
         xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14">Header
         Field Definitions</link>.
     </para>
+    <para>
+        The API returns the <code>Range Not Satisfiable (416)</code> response
+        code for any ranged &GET; requests that specify more than:
+    </para>
+    <itemizedlist>
+        <listitem>
+            <para>
+                Fifty ranges.
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Three overlapping ranges.
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Eight non-increasing ranges.
+            </para>
+        </listitem>
+    </itemizedlist>
     <section xml:id="storage_info">
         <title>Discoverability</title>
         <para>

api-ref/src/wadls/object-api/src/common.ent

@@ -7,62 +7,72 @@
         element="csapi:computeFault"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault503 '<response status="503" xmlns="http://wadl.dev.java.net/2009/02">
+<!ENTITY fault503 '
+<response status="503" xmlns="http://wadl.dev.java.net/2009/02">
     <representation mediaType="application/xml"
         element="csapi:serviceUnavailable"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault503macGeneration '<response status="503" xmlns="http://wadl.dev.java.net/2009/02">
+<!ENTITY fault503macGeneration '
+<response status="503" xmlns="http://wadl.dev.java.net/2009/02">
     <representation mediaType="application/xml"
         element="csapi:macGenerationFailure"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault400 '<response status="400" xmlns="http://wadl.dev.java.net/2009/02">
+<!ENTITY fault400 '
+<response status="400" xmlns="http://wadl.dev.java.net/2009/02">
     <representation mediaType="application/xml"
         element="csapi:badRequest"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault401 '<response status="401" xmlns="http://wadl.dev.java.net/2009/02">
+<!ENTITY fault401 '
+<response status="401" xmlns="http://wadl.dev.java.net/2009/02">
     <representation mediaType="application/xml"
         element="csapi:unauthorized"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault403 '<response status="403" xmlns="http://wadl.dev.java.net/2009/02">
+<!ENTITY fault403 '
+<response status="403" xmlns="http://wadl.dev.java.net/2009/02">
     <representation mediaType="application/xml"
         element="csapi:forbidden"/>
     <representation mediaType="application/json"/>
 </response>'>
-<!ENTITY fault404 '<response status="404" xmlns="http://wadl.dev.java.net/2009/02">
-            <representation mediaType="application/xml" element="csapi:NotFound"/>
-            <representation mediaType="application/json"/>
-        </response>'>
-<!ENTITY fault408 '<response status="408" xmlns="http://wadl.dev.java.net/2009/02">
-            <representation mediaType="application/xml" element="csapi:timeout"/>
-            <representation mediaType="application/json"/>
-        </response>'>
-<!ENTITY fault409 '<response status="409" xmlns="http://wadl.dev.java.net/2009/02">
-            <representation mediaType="application/xml" element="csapi:Conflict"/>
-            <representation mediaType="application/json"/>
-        </response>'>
-<!ENTITY fault411 '<response status="411" xmlns="http://wadl.dev.java.net/2009/02">
-            <representation mediaType="application/xml" element="csapi:lengthRequired"/>
-            <representation mediaType="application/json"/>
-        </response>'>
-<!ENTITY fault422 '<response status="422" xmlns="http://wadl.dev.java.net/2009/02">
-            <representation mediaType="application/xml" element="csapi:unprocessableEntity"/>
-            <representation mediaType="application/json"/>
-        </response>'>
+<!ENTITY fault404 '
+<response status="404" xmlns="http://wadl.dev.java.net/2009/02">
+    <representation mediaType="application/xml" element="csapi:NotFound"/>
+    <representation mediaType="application/json"/>
+</response>'>
+<!ENTITY fault408 '
+<response status="408" xmlns="http://wadl.dev.java.net/2009/02">
+    <representation mediaType="application/xml" element="csapi:timeout"/>
+    <representation mediaType="application/json"/>
+</response>'>
+<!ENTITY fault409 '
+<response status="409" xmlns="http://wadl.dev.java.net/2009/02">
+    <representation mediaType="application/xml" element="csapi:Conflict"/>
+    <representation mediaType="application/json"/>
+</response>'>
+<!ENTITY fault411 '
+<response status="411" xmlns="http://wadl.dev.java.net/2009/02">
+    <representation mediaType="application/xml" element="csapi:lengthRequired"/>
+    <representation mediaType="application/json"/>
+</response>'>
+<!ENTITY fault422 '
+<response status="422" xmlns="http://wadl.dev.java.net/2009/02">
+    <representation mediaType="application/xml" element="csapi:unprocessableEntity"/>
+    <representation mediaType="application/json"/>
+</response>'>
 <!-- Request headers -->
 <!ENTITY accept-requestHeader '
 <param xmlns="http://wadl.dev.java.net/2009/02" name="Accept"
     style="header" required="false" type="xsd:string">
     <wadl:doc xmlns="http://docbook.org/ns/docbook"
         xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
-        <para>Instead of using the <code>format</code> query
-            parameter, set this header to
-                <code>application/json</code>,
-                <code>application/xml</code>, or
-            <code>text/xml</code>.</para>
+        <para>
+            Instead of using the <code>format</code> query parameter, set this
+            header to <code>application/json</code>,
+            <code>application/xml</code>, or <code>text/xml</code>.
+        </para>
     </wadl:doc>
 </param>'>
 <!ENTITY account-meta-name-requestHeader '

api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl

@@ -494,6 +494,27 @@ Date: Fri, 17 Jan 2014 16:09:56 GMT</programlisting></para>
                 If the container does not exist, the call returns the
                 <code>Not Found (404)</code> response code.
             </para>
+            <para>
+                The operation returns the <code>Range Not Satisfiable (416)</code> response
+                code for any ranged &GET; requests that specify more than:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Fifty ranges.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Three overlapping ranges.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Eight non-increasing ranges.
+                    </para>
+                </listitem>
+            </itemizedlist>
         </wadl:doc>
         <request>
             <representation mediaType="application/xml">
@@ -541,7 +562,9 @@ Date: Fri, 17 Jan 2014 16:09:56 GMT</programlisting></para>
                 &container-meta-temp-url-key-requestHeader;
                 &container-meta-temp-url-key-2-requestHeader;
             </representation>
-        </response> &fault404; </method>
+        </response> &fault404;
+        <response status="416"/>
+    </method>
     <method name="PUT" id="createContainer">
         <!-- create container -->
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
@@ -889,6 +912,27 @@ Date: Thu, 16 Jan 2014 18:55:00 GMT
 &lt;html>&lt;h1>Not Found&lt;/h1>&lt;p>The resource could not be found.&lt;/p>&lt;/html></programlisting></para>
                 </listitem>
             </itemizedlist>
+            <para>
+                The operation returns the <code>Range Not Satisfiable (416)</code> response
+                code for any ranged &GET; requests that specify more than:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Fifty ranges.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Three overlapping ranges.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Eight non-increasing ranges.
+                    </para>
+                </listitem>
+            </itemizedlist>
         </wadl:doc>
         <request>
           <representation mediaType="application/xml">
@@ -918,7 +962,9 @@ Date: Thu, 16 Jan 2014 18:55:00 GMT
             &static-large-object-responseHeader;
             &trans-id-responseHeader; &Date-ResponseHeader;
           </representation>
-        </response> &fault404; </method>
+        </response> &fault404;
+        <response status="416"/>
+    </method>
     <method name="PUT" id="createOrReplaceObject">
         <!-- create, replace object -->
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
@@ -1220,8 +1266,10 @@ Date: Thu, 16 Jan 2014 21:13:19 GMT
 </programlisting></para>
                 </listitem>
             </itemizedlist>
-            <para>If the request succeeds, the operation returns the
-                    <code>200</code> response code.</para>
+            <para>
+                If the request succeeds, the operation returns the
+                <code>200</code> response code.
+            </para>
         </wadl:doc>
         <request>
           <representation mediaType="application/xml">