From cafe8a20aedb014798f349b1759e800f7cac5095 Mon Sep 17 00:00:00 2001
From: Atsushi SAKAI <sakaia@jp.fujitsu.com>
Date: Mon, 10 Aug 2015 19:43:43 +0900
Subject: [PATCH] Add GET servers API sorting REST API

Add sort_key and sort_dir discription
I add v2.1 only, if needed I plan to add v2 also.
But for v2 case, it need to existence "os-server-sort-keys" API.

Change-Id: I3d97652c925ef106421245a3a359b47949334240
Closes-Bug: #1398288
---
 .../src/wadls/compute-api/src/v2.1/common.ent | 56 +++++++++++++++++++
 .../src/v2.1/wadl/os-server-usage-v2.1.wadl   |  8 ++-
 api-ref/src/wadls/image-api/src/v2/common.ent |  2 -
 3 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/api-ref/src/wadls/compute-api/src/v2.1/common.ent b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
index 6d9076986..2a8349bb4 100644
--- a/api-ref/src/wadls/compute-api/src/v2.1/common.ent
+++ b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
@@ -480,6 +480,62 @@
    xml:lang="EN">
    <para>Filters the results by a specified host name in string format.</para>
 </wadl:doc>
+</param>
+<param xmlns="http://wadl.dev.java.net/2009/02" name="sort_key"
+   style="query" required="false" type="xsd:string" default="ALL">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
+   <para>
+      Sorts by the requested server attribute. Default is
+      <code>created</code>. You can specify multiple pairs of sort key and
+      sort direction query parameters. If you omit the sort direction in a
+      pair, the API uses the natural sorting direction of the server attribute
+      that is provided as the <code>sort_key</code>.
+   </para>
+</wadl:doc>
+</param>
+<param xmlns="http://wadl.dev.java.net/2009/02" name="sort_dir"
+   style="query" required="false" type="xsd:string" default="ALL">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
+  <para>
+    Sort direction. A valid value is <code>asc</code> (ascending) or
+    <code>desc</code> (descending). Default is <code>desc</code>. You can
+    specify multiple pairs of sort key and sort direction query parameters. If
+    you omit the sort direction in a pair, the API uses the natural sorting
+    direction of the server attribute that is provided as the
+    <code>sort_key</code>.
+  </para>
+</wadl:doc>
+</param>'>
+<!-- Server Details Parameters -->
+<!ENTITY serverListDetailsParameters '
+<param xmlns="http://wadl.dev.java.net/2009/02" name="sort_key"
+   style="query" required="false" type="xsd:string" default="ALL">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
+   <para>
+      Sorts by the requested server attribute. Default is
+      <code>created</code>. You can specify multiple pairs of sort key and
+      sort direction query parameters. If you omit the sort direction in a
+      pair, the API uses the natural sorting direction of the server attribute
+      that is provided as the <code>sort_key</code>.
+   </para>
+</wadl:doc>
+</param>
+<param xmlns="http://wadl.dev.java.net/2009/02" name="sort_dir"
+   style="query" required="false" type="xsd:string" default="ALL">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
+  <para>
+    Sort direction. A valid value is <code>asc</code> (ascending) or
+    <code>desc</code> (descending). Default is <code>desc</code>. You can
+    specify multiple pairs of sort key and sort direction query parameters. If
+    you omit the sort direction in a pair, the API uses the natural sorting
+    direction of the server attribute that is provided as the
+    <code>sort_key</code>.
+  </para>
+</wadl:doc>
 </param>'>
 <!-- Servers Extended Attributes Parameters -->
 <!ENTITY GetListServersDetailQueryParameters '
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
index 2f32de99e..8ff5b35a7 100644
--- a/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
+++ b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
@@ -77,9 +77,15 @@
     <method name="GET" id="returnListDetailServers">
         <wadl:doc xml:lang="EN" title="List details for servers"
             xmlns="http://docbook.org/ns/docbook">
-            <para role="shortdesc">List details for servers.
+            <para role="shortdesc">
+                Lists details for servers.
             </para>
         </wadl:doc>
+        <request>
+            <representation mediaType="application/json">
+                &serverListDetailsParameters;
+            </representation>
+        </request>
         <response status="200">
             <representation mediaType="application/json">
                 <wadl:doc xml:lang="EN" xmlns="http://docbook.org/ns/docbook">
diff --git a/api-ref/src/wadls/image-api/src/v2/common.ent b/api-ref/src/wadls/image-api/src/v2/common.ent
index 5ffc2549e..42381f821 100644
--- a/api-ref/src/wadls/image-api/src/v2/common.ent
+++ b/api-ref/src/wadls/image-api/src/v2/common.ent
@@ -189,11 +189,9 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
    <para>
-
       Sorts by one or more attribute and sort direction combinations. You can
       also set multiple sort keys and directions. Default direction is
       <code>desc</code>.
-
    </para>
    <para>For example:</para>
     <programlisting language="json">GET /v2/images?sort=name:asc,status:desc</programlisting>