Adds serialized response formats to End User Guide

With the moving of the Object Storage API content from a
long-form dev guide to a specification, some topics needed
to be added to the End User Guide. Also included linked
environment variables topic.

Change-Id: I6b8cee64e0bb7ea8ba7291aea31b4b7853f214a3
Partial-bug: 1392382

doc/user-guide/section_cli_swift_howto.xml

@@ -1,25 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <section xmlns="http://docbook.org/ns/docbook"
   xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-  version="5.0"
   xml:id="managing-openstack-object-storage-with-swift-cli">
-    <title>Manage objects and containers</title>
+  <title>Manage objects and containers</title>
-    <?dbhtml stop-chunking?>
+  <?dbhtml stop-chunking?>
-    <para>The OpenStack Object Storage service provides the
+  <para>The OpenStack Object Storage service provides the
-      <command>swift</command> client, which is a command-line interface (CLI).
+      <command>swift</command> client, which is a command-line
-    Use this client to list objects and containers, upload objects to
+    interface (CLI). Use this client to list objects and containers,
-    containers, and download or delete objects from containers. You can also
+    upload objects to containers, and download or delete objects from
-    gather statistics and update metadata for accounts, containers, and
+    containers. You can also gather statistics and update metadata for
-    objects.</para>
+    accounts, containers, and objects.</para>
-    <para>This client is based on the native swift client library,
+  <para>This client is based on the native swift client library,
-            <literal>client.py</literal>, which seamlessly
+      <literal>client.py</literal>, which seamlessly re-authenticates
-        re-authenticates if the current token expires during
+    if the current token expires during processing, retries operations
-        processing, retries operations multiple times, and provides a
+    multiple times, and provides a processing concurrency of
-        processing concurrency of 10.</para>
+    10.</para>
-    <section xml:id="cli_create_containers">
+  <section xml:id="cli_create_containers">
-      <title>Create and manage containers</title>
+    <title>Create and manage containers</title>
-      <itemizedlist>
+    <itemizedlist>
       <listitem>
         <para>To create a container, run the following command and replace
             <replaceable>CONTAINER</replaceable> with the name of your
@@ -33,18 +32,19 @@
         <para>To check the status of containers, run the following
           command:</para>
         <screen><prompt>$</prompt> <userinput>swift stat</userinput></screen>
-<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
+        <screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
 Containers: 2
 Objects: 3
 Bytes: 268826
 Accept-Ranges: bytes
 X-Timestamp: 1392683866.17952
 Content-Type: text/plain; charset=utf-8</computeroutput></screen>
-        <para>You can also use the <command>swift stat</command> command with the
+        <para>You can also use the <command>swift stat</command>
-        <replaceable>ACCOUNT</replaceable> or <replaceable>CONTAINER</replaceable>
+          command with the <replaceable>ACCOUNT</replaceable> or
-        names as parameters.</para>
+            <replaceable>CONTAINER</replaceable> names as
+          parameters.</para>
         <screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable></userinput></screen>
-<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
+        <screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
 Container: storage1
 Objects: 2
 Bytes: 240221
@@ -56,51 +56,56 @@ Accept-Ranges: bytes
 X-Timestamp: 1392683866.20180
 Content-Type: text/plain; charset=utf-8</computeroutput></screen>
       </listitem>
-      </itemizedlist>
+    </itemizedlist>
-    </section>
+  </section>
   <section xml:id="cli_manage_access_swift">
     <title>Manage access</title>
     <itemizedlist>
       <listitem>
-        <para>Users have roles on accounts. For example, a user with the admin
+        <para>Users have roles on accounts. For example, a user with
-          role has full access to all containers and objects in an account. You
+          the admin role has full access to all containers and objects
-          can set access control lists (ACLs) at the container level and support
+          in an account. You can set access control lists (ACLs) at
-          lists for read and write access, which you set with the
+          the container level and support lists for read and write
+          access, which you set with the
             <literal>X-Container-Read</literal> and
             <literal>X-Container-Write</literal> headers.</para>
-        <para>To give a user read access, use the <command>swift post</command>
+        <para>To give a user read access, use the <command>swift
-          command with the <parameter>-r</parameter> parameter. To give a user
+            post</command> command with the <parameter>-r</parameter>
-          write access, use the <parameter>-w</parameter> parameter.</para>
+          parameter. To give a user write access, use the
-        <para>The following example enables the <literal>testuser</literal> user
+            <parameter>-w</parameter> parameter.</para>
-          to read objects in the container:</para>
+        <para>The following example enables the
+            <literal>testuser</literal> user to read objects in the
+          container:</para>
         <screen><prompt>$</prompt> <userinput>swift post -r 'testuser'</userinput></screen>
-        <para>You can also use this command with a list of users.</para>
+        <para>You can also use this command with a list of
+          users.</para>
       </listitem>
       <listitem>
-        <para>If you use StaticWeb middleware to enable Object Storage to serve
+        <para>If you use StaticWeb middleware to enable Object Storage
-          public web content, use <literal>.r:</literal>, followed by a list of
+          to serve public web content, use <literal>.r:</literal>,
-          allowed referrers.</para>
+          followed by a list of allowed referrers.</para>
-        <para>The following command gives object access to all referring
+        <para>The following command gives object access to all
-          domains:</para>
+          referring domains:</para>
         <screen><prompt>$</prompt> <userinput>swift post -r '.r:*'</userinput></screen>
       </listitem>
     </itemizedlist>
   </section>
-    <section xml:id="cli_manage_objects">
+  <section xml:id="cli_manage_objects">
-      <title>Manage objects</title>
+    <title>Manage objects</title>
-      <itemizedlist>
+    <itemizedlist>
-        <listitem>
+      <listitem>
         <para>To upload an object to a container, run the following
           command:</para>
-      <screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
+        <screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
-        <para>To upload in chunks, for large files, run the following command:</para>
+        <para>To upload in chunks, for large files, run the following
-      <screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>CHUNK_SIZE</replaceable> <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
+          command:</para>
+        <screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>CHUNK_SIZE</replaceable> <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
       </listitem>
       <listitem>
         <para>To check the status of the object, run the following
           command:</para>
-      <screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
+        <screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
-<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
+        <screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
 Container: storage1
 Object: images
 Content Type: application/octet-stream
@@ -110,11 +115,12 @@ ETag: 82169623d55158f70a0d720f238ec3ef
 Meta Orig-Filename: images.jpg
 Accept-Ranges: bytes
 X-Timestamp: 1392684036.33306</computeroutput></screen>
-    </listitem>
+      </listitem>
       <listitem>
-        <para>To list the objects in a container, run the following command:</para>
+        <para>To list the objects in a container, run the following
+          command:</para>
         <screen><prompt>$</prompt> <userinput>swift list <replaceable>CONTAINER</replaceable></userinput></screen>
-        </listitem>
+      </listitem>
       <listitem>
         <para>To download an object from a container, run the
           following command:</para>
@@ -122,6 +128,8 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
       </listitem>
     </itemizedlist>
   </section>
-  <xi:include href="section_object-api-versioning.xml"/>
+  <xi:include href="section_object-api-env-vars.xml"/>
+  <xi:include href="section_object-api-response-formats.xml"/>
   <xi:include href="section_object-api-create-large-objects.xml"/>
+  <xi:include href="section_object-api-versioning.xml"/>
 </section>

doc/user-guide/section_object-api-env-vars.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="env-vars">
+    <title>Environment variables required to run examples</title>
+    <para>To run the cURL command examples for the Object Storage API
+        requests, set these environment variables:</para>
+    <variablelist>
+        <varlistentry>
+            <term><literal>publicURL</literal></term>
+            <listitem>
+                <para>The public URL that is the HTTP endpoint from
+                    where you can access Object Storage. It includes
+                    the Object Storage API version number and your
+                    account name. For example,
+                        <code>https://23.253.72.207/v1/my_account</code>.</para>
+            </listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><literal>token</literal></term>
+            <listitem>
+                <para>The authentication token for Object
+                    Storage.</para>
+            </listitem>
+        </varlistentry>
+    </variablelist>
+    <para>To obtain these values, run the <command>swift stat
+            -v</command> command.</para>
+    <para>As shown in this example, the public URL appears in the
+            <literal>StorageURL</literal> field, and the token appears
+        in the <literal>Auth Token</literal> field:</para>
+    <programlisting>StorageURL: https://23.253.72.207/v1/my_account
+Auth Token: {token}
+Account: my_account
+Containers: 2
+Objects: 3
+Bytes: 47
+Meta Book: MobyDick
+X-Timestamp: 1389453423.35964
+X-Trans-Id: txee55498935404a2caad89-0052dd3b77
+Content-Type: text/plain; charset=utf-8
+Accept-Ranges: bytes</programlisting>
+</section>

doc/user-guide/section_object-api-response-formats.xml

@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section [
+<!-- Useful for describing APIs -->
+<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
+]>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="serialized-response-formats">
+    <title>Serialized response formats</title>
+    <para>By default, the Object Storage API uses a
+            <literal>text/plain</literal> response format. In
+        addition, both JSON and XML data serialization response
+        formats are supported.</para>
+    <note>
+        <para>To run the cURL command examples, you must export <link
+                linkend="env-vars">environment
+            variables</link>.</para>
+    </note>
+    <para>To define the response format, use one of these
+        methods:</para>
+    <informaltable rules="all">
+        <thead>
+            <tr>
+                <th>Method</th>
+                <th>Description</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td><para><code>format=<replaceable>format</replaceable></code>
+                        query parameter</para></td>
+                <td>
+                    <para>Append this parameter to the URL for a &GET;
+                        request, where
+                            <replaceable>format</replaceable> is
+                            <code>json</code> or
+                        <code>xml</code>.</para>
+                </td>
+            </tr>
+            <tr>
+                <td><para><literal>Accept</literal> request
+                        header</para></td>
+                <td>
+                    <para>Include this header in the &GET; request.
+                        The valid header values are:</para>
+                    <variablelist>
+                        <varlistentry>
+                            <term><code>text/plain</code></term>
+                            <listitem>
+                                <para>Plain text response format. The
+                                   default.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term><code>application/jsontext</code></term>
+                            <listitem>
+                                <para>JSON data serialization response
+                                   format.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term><code>application/xml</code>or
+                                   <code>text/xml</code></term>
+                            <listitem>
+                                <para>XML data serialization response
+                                   format.</para>
+                            </listitem>
+                        </varlistentry>
+                    </variablelist>
+                </td>
+            </tr>
+        </tbody>
+    </informaltable>
+    <example>
+        <title>JSON example with format query parameter</title>
+        <para>For example, this request uses the
+                <parameter>format</parameter> query parameter to ask
+            for a JSON response:</para>
+        <screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"</userinput></screen>
+        <screen><computeroutput>HTTP/1.1 200 OK
+Content-Length: 96
+X-Account-Object-Count: 1
+X-Timestamp: 1389453423.35964
+X-Account-Meta-Subject: Literature
+X-Account-Bytes-Used: 14
+X-Account-Container-Count: 2
+Content-Type: application/json; charset=utf-8
+Accept-Ranges: bytes
+X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
+Date: Fri, 17 Jan 2014 15:59:33 GMT</computeroutput></screen>
+        <para>Object Storage lists container names with additional
+            information in JSON format:</para>
+        <programlisting language="json">[
+   {
+      "count":0,
+      "bytes":0,
+      "name":"janeausten"
+   },
+   {
+      "count":1,
+      "bytes":14,
+      "name":"marktwain"
+   }
+]</programlisting>
+    </example>
+    <example>
+        <title>XML example with Accept header</title>
+        <para>This request uses the <literal>Accept</literal> request
+            header to ask for an XML response:</para>
+        <screen><prompt>#</prompt> <userinput>curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H "Accept: application/xml; charset=utf-8"</userinput></screen>
+        <screen><computeroutput>HTTP/1.1 200 OK
+Content-Length: 263
+X-Account-Object-Count: 3
+X-Account-Meta-Book: MobyDick
+X-Timestamp: 1389453423.35964
+X-Account-Bytes-Used: 47
+X-Account-Container-Count: 2
+Content-Type: application/xml; charset=utf-8
+Accept-Ranges: bytes
+X-Trans-Id: txf0b4c9727c3e491694019-0052e03420
+Date: Wed, 22 Jan 2014 21:12:00 GMT</computeroutput></screen>
+        <para>Object Storage lists container names with additional
+            information in XML format:</para>
+        <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;account name="AUTH_73f0aa26640f4971864919d0eb0f0880">
+    &lt;container>
+        &lt;name>janeausten&lt;/name>
+        &lt;count>2&lt;/count>
+        &lt;bytes>33&lt;/bytes>
+    &lt;/container>
+    &lt;container>
+        &lt;name>marktwain&lt;/name>
+        &lt;count>1&lt;/count>
+        &lt;bytes>14&lt;/bytes>
+    &lt;/container>
+&lt;/account></programlisting>
+        <para>The remainder of the examples in this guide use
+            standard, non-serialized responses. However, all &GET;
+            requests that perform list operations accept the
+                <parameter>format</parameter> query parameter or
+                <literal>Accept</literal> request header.</para>
+    </example>
+</section>