Add an explanation for X-Newest header

Add a short explanation of the X-newest header in each section (account/container/object). Change-Id: I3a9ab126bf4fecf8d837d11850e09ef31f31ff7e Closes-Bug: #1193417
openstack-attic · Dec 11, 2013 · 7be4236 · 7be4236
1 parent 5682e33
commit 7be4236
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 0 deletions.
diff --git a/openstack-object-storage-dev/section_object-api-storage-container-svc.xml b/openstack-object-storage-dev/section_object-api-storage-container-svc.xml
@@ -69,6 +69,24 @@ format="SVG" scale="60"/>
             </tr>
         </tbody>
     </informaltable>
+    <variablelist>
+        <title>Optional headers for HEAD and GET</title>
+        <varlistentry>
+            <term><code>X-Newest</code></term>
+            <listitem>
+                <para>Set the optional <code>X-newest</code> header to
+                    <code>True</code> in HEAD and GET requests to have
+                    Object Storage return the latest version of the container.
+                    If set to <code>True</code>, Object Storage queries all
+                    replicas to return the most recent one. Without this header,
+                    Object Storage responds faster after it finds one valid replica.
+                    Because setting this header to <code>True</code> is more
+                    expensive for the back end, use it only when it is
+                    absolutely needed.
+                </para>
+            </listitem>
+        </varlistentry>
+    </variablelist>
     <para>All operations follow this format:</para>
     <example>
         <title>Storage Container Services HTTP Request</title>

diff --git a/openstack-object-storage-dev/section_object-api-storage-object-svc.xml b/openstack-object-storage-dev/section_object-api-storage-object-svc.xml
@@ -89,6 +89,24 @@ format="SVG" scale="60"/>
             </tr>
         </tbody>
     </informaltable>
+    <variablelist>
+        <title>Optional headers for HEAD and GET</title>
+        <varlistentry>
+            <term><code>X-Newest</code></term>
+            <listitem>
+                <para>Set the optional <code>X-newest</code> header to
+                    <code>True</code> in HEAD and GET requests to have
+                    Object Storage return the latest version of the object.
+                    If set to <code>True</code>, Object Storage queries all
+                    replicas to return the most recent one. Without this header,
+                    Object Storage responds faster after it finds one valid replica.
+                    Because setting this header to <code>True</code> is more
+                    expensive for the back end, use it only when it is
+                    absolutely needed.
+                </para>
+            </listitem>
+        </varlistentry>
+    </variablelist>
     <section xml:id="retrieve-object">
         <title>Get Object Details</title>
         <para>&GET; operations against an object are used to retrieve

diff --git a/openstack-object-storage-dev/section_object-api-storage_account_svc.xml b/openstack-object-storage-dev/section_object-api-storage_account_svc.xml
@@ -67,6 +67,24 @@ format="SVG" scale="60"/>
 
         </tbody>
     </informaltable>
+    <variablelist>
+        <title>Optional headers for HEAD and GET</title>
+        <varlistentry>
+            <term><code>X-Newest</code></term>
+            <listitem>
+                <para>Set the optional <code>X-newest</code> header to
+                    <code>True</code> in HEAD and GET requests to have
+                    Object Storage return the latest version of the account.
+                    If set to <code>True</code>, Object Storage queries all
+                    replicas to return the most recent one. Without this header,
+                    Object Storage responds faster after it finds one valid replica.
+                    Because setting this header to <code>True</code> is more
+                    expensive for the back end, use it only when it is
+                    absolutely needed.
+                </para>
+            </listitem>
+        </varlistentry>
+    </variablelist>
     <para>For example, the URL for the requests end with the OpenStack
         Object Storage account string, as follows:</para>
     <example>