From fdd21d91be9b5cf8490ebe7cd7d73d555917d468 Mon Sep 17 00:00:00 2001
From: tengqm <tengqim@cn.ibm.com>
Date: Tue, 3 Mar 2015 14:46:31 +0800
Subject: [PATCH] Revised API doc for cluster_create

---
 .../clustering-api/src/v1/clustering-api.wadl | 76 +++++++++++--------
 .../src/v1/samples/cluster_create.json        | 13 ++--
 .../src/v1/samples/cluster_create_resp.json   | 28 +++++--
 3 files changed, 71 insertions(+), 46 deletions(-)

diff --git a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/clustering-api.wadl b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/clustering-api.wadl
index baacb0e35..41366141d 100644
--- a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/clustering-api.wadl
+++ b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/clustering-api.wadl
@@ -8,15 +8,6 @@
 <!ENTITY POST   '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
 <!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
 
-<!-- Common descriptions for cases where a user supplies a new stack name -->
-<!ENTITY CLUSTER_NAME_FORMAT 'The value must be unique within a project. The
-name must start with an ASCII letter and can contain ASCII letters, digits,
-underscores, periods, and hyphens. Specifically, the name must match the
-regular expression <code>^[a-zA-Z][a-zA-Z0-9_.-]*$</code>.'>
-<!ENTITY CLUSTER_NAME_CREATE_DESC 'A name for the new cluster. 
-&CLUSTER_NAME_FORMAT; <note><para>Deleting or abandoning a cluster may not
-make the cluster name available for reuse, or the ability to reuse a cluster
-name could be delayed for an unspecified time.</para></note>'>
 ]>
 
 <application xmlns="http://wadl.dev.java.net/2009/02"
@@ -278,7 +269,7 @@ name could be delayed for an unspecified time.</para></note>'>
                 <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
                     <xsdxt:code href="samples/cluster_list_resp.json"/>
                 </wadl:doc>
-                <param name="clusters" style="query" required="false">
+                <param name="clusters" style="plain" required="false">
                     <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
                         <para>List of cluster records where each record contains fields like
                             <code>created_time</code>, <code>id</code>, <code>name</code>,
@@ -299,41 +290,60 @@ name could be delayed for an unspecified time.</para></note>'>
                 <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
                     <xsdxt:code href="samples/cluster_create.json"/>
                 </wadl:doc>
-                <param name="name" style="plain" required="true">
-                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>&CLUSTER_NAME_CREATE_DESC;</para>
-                    </wadl:doc>
+                <param name="cluster" style="plain" required="true">
                 </param>
-                <param name="profile_id" style="plain" required="true">
                     <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>ID of profile to be used for this cluster.</para>
-                    </wadl:doc>
-                </param>
-                <param name="size" style="plain" required="false">
-                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>Initial size of the cluster.</para>
-                    </wadl:doc>
-                </param>
-                <param name="timeout" style="plain" required="false">
-                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>Cluster creation timeout as number of minutes.</para>
-                    </wadl:doc>
-                </param>
-                <param name="tags" style="plain" required="false">
-                    <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>A collection of key-value pairs to be associated with the stack.</para>
+                        <para>A map that contains details for the cluster to be created.</para>
+                        <itemizedlist xml:id="cluster_create_body">
+                            <title>Cluster Create Request Body</title>
+                            <listitem>
+                                <para>
+                                    <code>name</code> Name for the cluster to be created. (required).
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>parent</code> ID of parent cluster if the new cluster is to be
+                                    a nested cluster. (optional).
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>profile_id</code> ID or name of profile to be used by the cluster.
+                                    (required).
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>size</code> Initial size of the cluster, default to 0.  (required).
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>timeout</code> Cluster creation timeout as number of minutes.
+                                    Default to 60. (optional).
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    <code>tags</code> List of key-value pairs that will be associated with
+                                    the cluster. (optional).
+                                </para>
+                            </listitem>
+                        </itemizedlist> 
                     </wadl:doc>
                 </param>
             </representation>
         </request>
-        <response status="201">
+        <response status="200">
             <representation mediaType="application/json">
                 <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
                     <xsdxt:code href="samples/cluster_create_resp.json" />
                 </wadl:doc>
                 <param name="cluster" style="plain" required="true">
                     <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-                        <para>A dictionary containing the <code>id</code> of and <code>link</code> to the cluster.</para>
+                        <para>A map containing the <code>id</code>, <code>name</code>, <code>status</code>,
+                            and many other fields of the cluster under creation.</para>
                     </wadl:doc>
                 </param>
             </representation>
diff --git a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create.json b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create.json
index feb27fcd6..b9fea8115 100644
--- a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create.json
+++ b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create.json
@@ -1,9 +1,10 @@
 {
-    "name": "testcluster",
-    "profile_id": "40be8d1a-3eb9-40de-8abd-43237517384f",
-    "size": 5,
-    "timeout": 60,
-    "tags": {
-        "owner": "Thomas",
+    "cluster": {
+        "name": "test_cluster",
+        "parent": null,
+        "profile_id": "mystack",
+        "size": "1",
+        "tags": {},
+        "timeout": null
     }
 }
diff --git a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create_resp.json b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create_resp.json
index b9b656da2..499ae304b 100644
--- a/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create_resp.json
+++ b/doc/api-site/api-ref/src/wadls/clustering-api/src/v1/samples/cluster_create_resp.json
@@ -1,11 +1,25 @@
 {
     "cluster": {
-        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
-        "links": [
-            {
-                "href": "http://192.168.12.34:8778/v1/eb1c63a4f77141548385f113a28f0f52/clusters/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
-                "rel": "self"
-            }
-        ]
+        "action": "bbf4558b-9fa3-482a-93c2-a4aa5cc85317", 
+        "created_time": null, 
+        "data": {}, 
+        "deleted_time": null, 
+        "domain": "", 
+        "id": "45edadcb-c73b-4920-87e1-518b2f29f54b", 
+        "init_time": null, 
+        "name": "test_cluster", 
+        "nodes": [], 
+        "parent": null, 
+        "policies": [], 
+        "profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a", 
+        "profile_name": "mystack", 
+        "project": "6e18cc2bdbeb48a5b3cad2dc499f6804", 
+        "size": 1, 
+        "status": "INIT", 
+        "status_reason": "Initializing", 
+        "tags": {}, 
+        "timeout": null, 
+        "updated_time": null, 
+        "user": "admin"
     }
 }