From 819802a73466cfac1ba0402d214a05fefebea344 Mon Sep 17 00:00:00 2001
From: tengqm <tengqim@cn.ibm.com>
Date: Fri, 29 Jan 2016 09:44:01 -0500
Subject: [PATCH] Revise cluster service API

There have been some changes to Senlin clustering API V1 recently. This
patch revises the API documentation so that it is synchronized with the
code development.

Change-Id: I3b8f0d02fad6d589ecc0216471c6192ab563c5d1
---
 api-ref/src/docbkx/ch_clustering-v1.xml       |  5 +-
 .../wadls/clustering-api/src/v1/common.ent    |  9 --
 .../src/v1/samples/cluster-check-request.json |  3 +
 .../v1/samples/cluster-create-request.json    |  1 -
 .../v1/samples/cluster-create-response.json   |  1 -
 .../v1/samples/cluster-recover-request.json   |  5 +
 .../src/v1/samples/cluster-show-response.json |  1 -
 .../v1/samples/cluster-update-request.json    |  1 -
 .../v1/samples/cluster-update-response.json   |  1 -
 .../v1/samples/clusters-list-response.json    |  1 -
 .../src/v1/samples/node-check-request.json    |  3 +
 .../src/v1/samples/node-recover-request.json  |  5 +
 .../src/v1/wadl/clustering-api.wadl           | 92 +++++++++++++++----
 13 files changed, 94 insertions(+), 34 deletions(-)
 create mode 100644 api-ref/src/wadls/clustering-api/src/v1/samples/cluster-check-request.json
 create mode 100644 api-ref/src/wadls/clustering-api/src/v1/samples/cluster-recover-request.json
 create mode 100644 api-ref/src/wadls/clustering-api/src/v1/samples/node-check-request.json
 create mode 100644 api-ref/src/wadls/clustering-api/src/v1/samples/node-recover-request.json

diff --git a/api-ref/src/docbkx/ch_clustering-v1.xml b/api-ref/src/docbkx/ch_clustering-v1.xml
index 0cea628e3..f14449b37 100644
--- a/api-ref/src/docbkx/ch_clustering-v1.xml
+++ b/api-ref/src/docbkx/ch_clustering-v1.xml
@@ -66,7 +66,7 @@
                 <wadl:method href="#deleteCluster"/>
             </wadl:resource>
             <wadl:resource href="../wadls/clustering-api/src/v1/wadl/clustering-api.wadl#cluster_actions">
-                <wadl:method href="#cluster_action"/>
+                <wadl:method href="#clusterAction"/>
             </wadl:resource>
         </wadl:resources>
     </section>
@@ -115,6 +115,9 @@
                 <wadl:method href="#updateNode"/>
                 <wadl:method href="#deleteNode"/>
             </wadl:resource>
+            <wadl:resource href="../wadls/clustering-api/src/v1/wadl/clustering-api.wadl#node_actions">
+                <wadl:method href="#nodeAction"/>
+            </wadl:resource>
         </wadl:resources>
     </section>
     <section xml:id="policies">
diff --git a/api-ref/src/wadls/clustering-api/src/v1/common.ent b/api-ref/src/wadls/clustering-api/src/v1/common.ent
index f5e1cc7e7..16d14e550 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/common.ent
+++ b/api-ref/src/wadls/clustering-api/src/v1/common.ent
@@ -347,15 +347,6 @@
         </para>
     </wadl:doc>
 </param>
-<param name="permission" style="plain" required="false"
-    xmlns="http://wadl.dev.java.net/2009/02" type="xsd:string">
-    <wadl:doc xmlns="http://docbook.org/ns/docbook"
-        xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
-        <para>
-            The default permission of the profile.
-        </para>
-    </wadl:doc>
-</param>
 <param name="metadata" style="plain" required="false"
     xmlns="http://wadl.dev.java.net/2009/02" type="xsd:list">
     <wadl:doc xmlns="http://docbook.org/ns/docbook"
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-check-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-check-request.json
new file mode 100644
index 000000000..6d831ea62
--- /dev/null
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-check-request.json
@@ -0,0 +1,3 @@
+{
+    "check": {}
+}
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-request.json
index ec71b3fa6..735b2fef4 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-request.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-request.json
@@ -5,7 +5,6 @@
         "metadata": {},
         "min_size": 0,
         "name": "test_cluster",
-        "parent": null,
         "profile_id": "mystack",
         "timeout": null
     }
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-response.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-response.json
index 789895c71..0c80604db 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-response.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-create-response.json
@@ -12,7 +12,6 @@
         "min_size": 0,
         "name": "test_cluster",
         "nodes": [],
-        "parent": null,
         "policies": [],
         "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
         "profile_name": "mystack",
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-recover-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-recover-request.json
new file mode 100644
index 000000000..84273532f
--- /dev/null
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-recover-request.json
@@ -0,0 +1,5 @@
+{
+    "recover": {
+        "operation": "rebuild"
+    }
+}
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-show-response.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-show-response.json
index 90d6d99c6..6a2d7af04 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-show-response.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-show-response.json
@@ -11,7 +11,6 @@
         "min_size": 0,
         "name": "test_cluster",
         "nodes": [],
-        "parent": null,
         "policies": [],
         "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
         "profile_name": "mystack",
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-request.json
index ba802042f..bf8c4892b 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-request.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-request.json
@@ -2,7 +2,6 @@
     "cluster": {
         "metadata": null,
         "name": null,
-        "parent": null,
         "profile_id": null,
         "timeout": "30"
     }
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-response.json b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-response.json
index ae9900fb5..139dba10e 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-response.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/cluster-update-response.json
@@ -11,7 +11,6 @@
         "min_size": 0,
         "name": "test_cluster",
         "nodes": [],
-        "parent": null,
         "policies": [],
         "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
         "profile_name": "mystack",
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/clusters-list-response.json b/api-ref/src/wadls/clustering-api/src/v1/samples/clusters-list-response.json
index 295d98b49..5d9ec11dc 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/samples/clusters-list-response.json
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/clusters-list-response.json
@@ -16,7 +16,6 @@
                 "ecc23d3e-bb68-48f8-8260-c9cf6bcb6e61",
                 "da1e9c87-e584-4626-a120-022da5062dac"
             ],
-            "parent": null,
             "policies": [],
             "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
             "profile_name": "mystack",
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/node-check-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/node-check-request.json
new file mode 100644
index 000000000..6d831ea62
--- /dev/null
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/node-check-request.json
@@ -0,0 +1,3 @@
+{
+    "check": {}
+}
diff --git a/api-ref/src/wadls/clustering-api/src/v1/samples/node-recover-request.json b/api-ref/src/wadls/clustering-api/src/v1/samples/node-recover-request.json
new file mode 100644
index 000000000..84273532f
--- /dev/null
+++ b/api-ref/src/wadls/clustering-api/src/v1/samples/node-recover-request.json
@@ -0,0 +1,5 @@
+{
+    "recover": {
+        "operation": "rebuild"
+    }
+}
diff --git a/api-ref/src/wadls/clustering-api/src/v1/wadl/clustering-api.wadl b/api-ref/src/wadls/clustering-api/src/v1/wadl/clustering-api.wadl
index a6baafbe4..35691df77 100644
--- a/api-ref/src/wadls/clustering-api/src/v1/wadl/clustering-api.wadl
+++ b/api-ref/src/wadls/clustering-api/src/v1/wadl/clustering-api.wadl
@@ -60,7 +60,7 @@
                     <method href="#updateCluster"/>
                     <method href="#deleteCluster"/>
                     <resource id="cluster_actions" path="actions">
-                        <method href="#cluster_action"/>
+                        <method href="#clusterAction"/>
                     </resource>
                     <resource id="cluster_policies" path="policies">
                         <method href="#listClusterPolicies"/>
@@ -79,6 +79,9 @@
                     <method href="#showNode"/>
                     <method href="#updateNode"/>
                     <method href="#deleteNode"/>
+                    <resource id="node_actions" path="actions">
+                        <method href="#nodeAction"/>
+                    </resource>
                 </resource>
             </resource>
             <resource id="actions" path="actions">
@@ -163,21 +166,6 @@
                         </para>
                     </wadl:doc>
                 </param>
-                <param name="show_nested" style="query" required="false"
-                    xmlns="http://wadl.dev.java.net/2009/02" type="xsd:boolean">
-                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>
-                            Includes nested clusters in or excludes nested
-                            clusters from the cluster list.
-                        </para>
-                        <para>
-                            Set to <code>False</code> to exclude nested
-                            clusters from the cluster list. Set to
-                            <code>True</code> to include nested clusters in
-                            the cluster list. Default is <code>False</code>.
-                        </para>
-                    </wadl:doc>
-                </param>
             </representation>
         </request>
         <response status="200">
@@ -284,7 +272,7 @@
             </representation>
         </response>
     </method>
-    <method name="POST" id="cluster_action">
+    <method name="POST" id="clusterAction">
         <wadl:doc xml:lang="EN" title="Trigger cluster action"
             xmlns="http://docbook.org/ns/docbook">
             <para role="shortdesc">
@@ -344,6 +332,21 @@
                                     <xsdxt:code href="../samples/cluster-resize-request.json"/>
                                 </para>
                             </listitem>
+                            <listitem>
+                                <para>
+                                    <code>check</code> Check the health status
+                                    of a cluster. For example:
+                                    <xsdxt:code href="../samples/cluster-check-request.json"/>
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>recover</code> Recover a cluster from
+                                    its current unhealthy status. For example:
+                                    <xsdxt:code href="../samples/cluster-recover-request.json"/>
+                                </para>
+                            </listitem>
+
                             <listitem>
                                 <para>
                                     <code>policy_attach</code> Attach a policy
@@ -362,7 +365,7 @@
                             </listitem>
                             <listitem>
                                 <para>
-                                    <code>updatePolicy</code> Update the
+                                    <code>policy_update</code> Update the
                                     policy attachment. Specify the policy ID and
                                     property settings in the request body:
                                     <xsdxt:code href="../samples/cluster-policy-update-request.json"/>
@@ -1202,6 +1205,59 @@
             </representation>
         </response>
     </method>
+    <method name="POST" id="nodeAction">
+        <wadl:doc xml:lang="EN" title="Trigger node action"
+            xmlns="http://docbook.org/ns/docbook">
+            <para role="shortdesc">
+                Triggers an action on a node.
+            </para>
+        </wadl:doc>
+        <request>
+            <representation mediaType="application/json">
+                <param name="action" style="plain" required="true"
+                    xmlns="http://wadl.dev.java.net/2009/02" type="xsd:string">
+                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+                        <para>
+                            The action to trigger.
+                        </para>
+                        <para>
+                            Each action takes a different set of parameters.
+                        </para>
+                        <para>
+                            Supported actions include:
+                        </para>
+                        <itemizedlist>
+                            <listitem>
+                                <para>
+                                    <code>check</code> Check the health status
+                                    of a node. For example:
+                                    <xsdxt:code href="../samples/node-check-request.json"/>
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>recover</code> Recover a node from
+                                    its current unhealthy status. For example:
+                                    <xsdxt:code href="../samples/node-recover-request.json"/>
+                                </para>
+                            </listitem>
+                        </itemizedlist>
+                    </wadl:doc>
+                </param>
+            </representation>
+        </request>
+        <response status="202">
+            <representation mediaType="application/json">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+                    <para>
+                        The <code>Location</code> response header contains the
+                        action that the request initiates.
+                    </para>
+                </wadl:doc>
+                &actionLocationParameter;
+            </representation>
+        </response>
+    </method>
     <method name="GET" id="listReceivers">
         <wadl:doc xml:lang="EN" title="List receivers" xmlns="http://docbook.org/ns/docbook">
             <para role="shortdesc">