From 2c14a2089d078c982edea14579e5d1128a388f1e Mon Sep 17 00:00:00 2001
From: Steven Kaufer <kaufer@us.ibm.com>
Date: Wed, 7 Jan 2015 20:34:18 +0000
Subject: [PATCH] Add Sorting Guidelines

Adds sorting guidelines to the existing pagination and filtering
document.

Note that a cross-project spec for CLI sorting guidelines is closely
related:
https://review.openstack.org/#/c/145544

Change-Id: I5bb32b1abf671578d7163ee24fe25d9406783ca9
---
 guidelines/pagination_filter_sort.rst | 64 +++++++++++++++++++++++++++
 guidelines/pagination_filtering.rst   | 22 ---------
 2 files changed, 64 insertions(+), 22 deletions(-)
 create mode 100644 guidelines/pagination_filter_sort.rst
 delete mode 100644 guidelines/pagination_filtering.rst

diff --git a/guidelines/pagination_filter_sort.rst b/guidelines/pagination_filter_sort.rst
new file mode 100644
index 0000000..11f15a2
--- /dev/null
+++ b/guidelines/pagination_filter_sort.rst
@@ -0,0 +1,64 @@
+Pagination, Filtering, and Sorting
+==================================
+
+This topic document serves to provide guidance on how to handle the
+pagination of large result sets and the best ways to provide filtering
+and sorting capabilities in a project's public REST API.
+
+Pagination
+----------
+
+**TODO** Discuss the methods currently used to paginate in OpenStack APIs.
+
+**TODO** Make a proposal/decision on the recommended way to implement
+pagination.
+
+Filtering
+---------
+
+**TODO** Discuss the methods currently used to filter in OpenStack APIs.
+
+**TODO** Make a proposal/decision on the recommended way to implement
+filtering.
+
+Sorting
+-------
+
+Sorting is determined through the use of the 'sort' query string parameter. The
+value of this parameter is a comma-separated list of sort keys. Sort directions
+can optionally be appended to each sort key, separated by the ':' character.
+
+The supported sort directions are either 'asc' for ascending or 'desc' for
+descending.
+
+The caller may (but is not required to) specify a sort direction for each key.
+If a sort direction is not specified for a key, then a default is set by the
+server.
+
+For example:
+
+- Only sort keys specified:
+
+  + ``sort=key1,key2,key3``
+  + 'key1' is the first key, 'key2' is the second key, etc.
+  + Sort directions are defaulted by the server
+
+- Some sort directions specified:
+
+  + ``sort=key1:asc,key2,key3``
+  + Any sort key without a corresponding direction is defaulted
+  + 'key1' is the first key (ascending order), 'key2' is the second key
+    (direction defaulted by the server), etc.
+
+- Equal number of sort keys and directions specified:
+
+  + ``sort=key1:asc,key2:desc,key3:asc``
+  + Each key is paired with the corresponding direction
+  + 'key1' is the first key (ascending order), 'key2' is the second key
+    (descending order), etc.
+
+Note that many projects have implemented sorting using repeating 'sort_key'
+and 'sort_dir' query string parameters, see [1]. As these projects adopt these
+guidelines, they should deprecate the older parameters appropriately.
+
+[1]: https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting
diff --git a/guidelines/pagination_filtering.rst b/guidelines/pagination_filtering.rst
deleted file mode 100644
index b85b302..0000000
--- a/guidelines/pagination_filtering.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-Pagination and Filtering
-========================
-
-This topic document serves to provide guidance on how to handle the
-pagination of large result sets and the best ways to provide filtering
-capabilities in a project's public REST API.
-
-Pagination
-----------
-
-**TODO** Discuss the methods currently used to paginate in OpenStack APIs.
-
-**TODO** Make a proposal/decision on the recommended way to implement
-pagination.
-
-Filtering
----------
-
-**TODO** Discuss the methods currently used to filter in OpenStack APIs.
-
-**TODO** Make a proposal/decision on the recommended way to implement
-filtering.