From e0e443e89f50f71d416b6f2678e22be2383ca227 Mon Sep 17 00:00:00 2001
From: Erik Wilson <erik.wilson@rackspace.com>
Date: Fri, 12 Dec 2014 16:10:35 -0600
Subject: [PATCH] Adds pseudo-hierarchical folders info 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.

Change-Id: Ic1616a970355707a48997e5b006e68164fa731f9
Partial-bug: 1392382
---
 doc/user-guide/section_cli_swift_howto.xml    |  1 +
 ...section_object-api-pseudo-hier-folders.xml | 80 +++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 doc/user-guide/section_object-api-pseudo-hier-folders.xml

diff --git a/doc/user-guide/section_cli_swift_howto.xml b/doc/user-guide/section_cli_swift_howto.xml
index 2e471e6abb..6e9c720489 100644
--- a/doc/user-guide/section_cli_swift_howto.xml
+++ b/doc/user-guide/section_cli_swift_howto.xml
@@ -134,4 +134,5 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
   <xi:include href="section_object-api-create-large-objects.xml"/>
   <xi:include href="section_object-api-large-lists.xml"/>
   <xi:include href="section_object-api-archive-auto-extract.xml"/>
+  <xi:include href="section_object-api-pseudo-hier-folders.xml"/>
 </section>
diff --git a/doc/user-guide/section_object-api-pseudo-hier-folders.xml b/doc/user-guide/section_object-api-pseudo-hier-folders.xml
new file mode 100644
index 0000000000..fef2d9fa90
--- /dev/null
+++ b/doc/user-guide/section_object-api-pseudo-hier-folders.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section[ <!ENTITY % openstack SYSTEM "../common/entities/openstack.ent"> %openstack; ]>
+<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="pseudo-hierarchical-folders-directories">
+    <title>Pseudo-hierarchical folders and directories</title>
+    <para>Although you cannot nest directories in OpenStack Object
+        Storage, you can simulate a hierarchical structure within a
+        single container by adding forward slash characters
+            (<literal>/</literal>) in the object name. To navigate the
+        pseudo-directory structure, you can use the
+            <code>delimiter</code> query parameter. This example shows
+        you how to use pseudo-hierarchical folders and
+        directories.</para>
+    <note>
+        <para>In this example, the objects reside in a container
+            called <code>backups</code>. Within that container, the
+            objects are organized in a pseudo-directory called
+                <code>photos</code>. The container name is not
+            displayed in the example, but it is a part of the object
+            URLs. For instance, the URL of the picture
+                <code>me.jpg</code> is
+                <uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.</para>
+    </note>
+    <example>
+        <title>List pseudo-hierarchical folders request: HTTP</title>
+        <para>To display a list of all the objects in the storage
+            container, use &GET; without a <code>delimiter</code> or
+                <code>prefix</code>.</para>
+        <screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups</userinput></screen>
+        <para>The system returns status code 2xx (between 200 and 299,
+            inclusive) and the requested list of the objects.</para>
+        <screen><computeroutput>photos/animals/cats/persian.jpg
+photos/animals/cats/siamese.jpg
+photos/animals/dogs/corgi.jpg
+photos/animals/dogs/poodle.jpg
+photos/animals/dogs/terrier.jpg
+photos/me.jpg
+photos/plants/fern.jpg
+photos/plants/rose.jpg</computeroutput></screen>
+        <para>Use the delimiter parameter to limit the displayed
+            results. To use <code>delimiter</code> with
+            pseudo-directories, you must use the parameter slash (<literal>/</literal>).</para>
+        <screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?delimiter=/</userinput></screen>
+        <para>The system returns status code 2xx (between 200 and 299,
+            inclusive) and the requested matching objects. Because you
+            use the slash, only the pseudo-directory
+                <code>photos/</code> displays. The returned values
+            from a slash <code>delimiter</code> query are not real
+            objects. They have a content-type of
+                <literal>application/directory</literal> and are in
+            the <literal>subdir</literal> section of JSON and XML
+            results.</para>
+        <screen><computeroutput>photos/</computeroutput></screen>
+        <para>Use the <code>prefix</code> and <code>delimiter</code>
+            parameters to view the objects inside a pseudo-directory,
+            including further nested pseudo-directories.</para>
+        <screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?prefix=photos/&#38;delimiter=/</userinput></screen>
+        <para>The system returns status code 2xx (between 200 and 299,
+            inclusive) and the objects and pseudo-directories within
+            the top level pseudo-directory.</para>
+        <screen><computeroutput>photos/animals/
+photos/me.jpg
+photos/plants/</computeroutput></screen>
+        <para>You can create an unlimited number of nested
+            pseudo-directories. To navigate through them, use a longer
+                <code>prefix</code> parameter coupled with the
+                <code>delimiter</code> parameter. In this sample
+            output, there is a pseudo-directory called
+                <code>dogs</code> within the pseudo-directory
+                <code>animals</code>. To navigate directly to the
+            files contained within <code>dogs</code>, enter the
+            following command:</para>
+        <screen><prompt>$</prompt> <userinput>curl -X GET -i -H "X-Auth-Token: $token" $publicurl/v1/AccountString/backups?prefix=photos/animals/dogs/&#38;delimiter=/</userinput></screen>
+        <para>The system returns status code 2xx (between 200 and 299,
+            inclusive) and the objects and pseudo-directories within
+            the nested pseudo-directory.</para>
+        <screen><computeroutput>photos/animals/dogs/corgi.jpg
+photos/animals/dogs/poodle.jpg
+photos/animals/dogs/terrier.jpg</computeroutput></screen>
+    </example>
+</section>