doc: also add reverse option to pagination doc

Change-Id: I4ee5a52ec9fb5f1920cd6869f6b1245c3787391c

1 files changed, 34 insertions, 0 deletions

diff --git a/doc/source/api/pagination.rst b/doc/source/api/pagination.rst
index 2d898b1de..8af0f42ba 100644
--- a/doc/source/api/pagination.rst
+++ b/doc/source/api/pagination.rst
@@ -5,6 +5,7 @@ Page through large lists of containers or objects
 If you have a large number of containers or objects, you can use the
 ``marker``, ``limit``, and ``end_marker`` parameters to control
 how many items are returned in a list and where the list starts or ends.
+If you want to page backwards you can use the ``reverse`` parameter.
 
 * marker
     When you request a list of containers or objects, Object Storage
@@ -29,6 +30,11 @@ how many items are returned in a list and where the list starts or ends.
     ``end_marker`` parameter value. You must URL-encode the
     ``end_marker`` value before you send the HTTP request.
 
+* reverse
+    By default, listings are returned sorted by name, ascending. If you
+    include the ``reverse=true`` query parameter, the listing will be
+    returned sorted by name, descending.
+
 To page through a large list of containers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -101,3 +107,31 @@ Assume the following list of container names:
 
    You receive a result set of all container names before the
    ``end-marker`` value.
+
+#. Use the ``reverse`` parameter to work from the back of the
+   list:
+
+   .. code-block:: console
+
+      # curl -i $publicURL/?reverse=true -X GET -H \"
+         X-Auth-Token: $token"
+
+   .. code-block:: console
+
+      pears
+      oranges
+      kiwis
+      bananas
+      apples
+
+#. You can also combine parameters:
+
+   .. code-block:: console
+
+      # curl -i $publicURL/?reverse=true&end_marker=kiwis -X GET -H \"
+         X-Auth-Token: $token"
+
+   .. code-block:: console
+
+      pears
+      oranges