From d2f3f8ccd9d3137a285ae292bc7b2bdbfb01728b Mon Sep 17 00:00:00 2001
From: "Ryan S. Brown" <sb@ryansb.com>
Date: Wed, 5 Nov 2014 09:18:12 -0500
Subject: [PATCH] Add documentation for update-preview endpoint

This adds API docs for a new endpoint created to check the actions of a
stack update without actually doing anything.

Related Heat change:
https://review.openstack.org/#/c/122473/

Co-Authored-By: Jason Dunsmore <jasondunsmore@gmail.com>
Change-Id: I2ef30b9108a106045ec0ef1e380e47803659fda5
BP: update-dry-run
---
 api-ref/src/docbkx/ch_orchestration-v1.xml    |  4 +
 .../src/v1/orchestration-api.wadl             | 82 +++++++++++++++++++
 .../v1/samples/stack_update_preview_resp.json | 67 +++++++++++++++
 3 files changed, 153 insertions(+)
 create mode 100644 api-ref/src/wadls/orchestration-api/src/v1/samples/stack_update_preview_resp.json

diff --git a/api-ref/src/docbkx/ch_orchestration-v1.xml b/api-ref/src/docbkx/ch_orchestration-v1.xml
index a36e11480..fcd5560ff 100644
--- a/api-ref/src/docbkx/ch_orchestration-v1.xml
+++ b/api-ref/src/docbkx/ch_orchestration-v1.xml
@@ -40,6 +40,10 @@
         <wadl:resource
              href="../wadls/orchestration-api/src/v1/orchestration-api.wadl#preview">
              <wadl:method href="#stack_preview"/>
+        </wadl:resource>
+        <wadl:resource
+             href="../wadls/orchestration-api/src/v1/orchestration-api.wadl#update_preview">
+             <wadl:method href="#stack_update_preview"/>
         </wadl:resource>
          <wadl:resource
              href="../wadls/orchestration-api/src/v1/orchestration-api.wadl#stack_name">
diff --git a/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl b/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
index eb46c4b9c..0400e30a7 100644
--- a/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
+++ b/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
@@ -68,6 +68,9 @@
                      <method href="#stack_show"/>
                      <method href="#stack_update"/>
                      <method href="#stack_delete"/>
+                     <resource path="preview" id="update_preview">
+                       <method href="#stack_update_preview"/>
+                     </resource>
                      <resource path="abandon" id="abandon">
                         <method href="#stack_abandon"/>
                      </resource>
@@ -1128,6 +1131,85 @@
       &notFound;
       &intServerErr;
    </method>
+   <method name="POST" id="stack_update_preview">
+       <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+           title="Preview stack update">
+           <para role="shortdesc">Preview an update for a specified stack</para>
+       </wadl:doc>
+       <request>
+          <representation mediaType="application/json">
+             <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                xmlns:wadl="http://wadl.dev.java.net/2009/02"
+                xml:lang="EN">
+                <xsdxt:code href="samples/stack_update.json"/>
+             </wadl:doc>
+             &templateUrlParameter;
+             &templateParameter;
+             &environmentParameterOptional;
+             &filesParameter;
+             &tagsParameter;
+             <param xmlns="http://wadl.dev.java.net/2009/02" name="parameters" style="plain" required="false">
+             <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                xml:lang="EN">
+                <para>
+                   This parameter supplies updated arguments for
+                   parameters defined in the stack template.
+                </para>
+                <para>
+                   The value is a JSON object, where each key is the name of a
+                   parameter defined in the template and the associated value
+                   is the argument to use for that parameter when instantiating
+                   the template. The following code shows the general structure
+                   of this parameter. In the example, <code>a</code> and
+                   <code>b</code> are the names of two parameters defined in
+                   the template.
+                   <programlisting language="json">{ ...
+                      "parameters": {
+                      "a": "Value",
+                      "b": "3"
+                      }
+                      ... }
+                   </programlisting>
+                </para>
+                <para>
+                   While the service accepts JSON numbers for parameters with
+                   the type <code>number</code> and JSON objects for parameters
+                   with the type <code>json</code>, all parameter values are
+                   converted to their string representation for storage in the
+                   created Stack. Clients are encouraged to send all parameter
+                   values using their string representation for consistency
+                   between requests and responses from the Orchestration
+                   service.
+                </para>
+                <para>
+                   You must specify a value for each template parameter that
+                   does not have a default value. However, this parameter
+                   cannot contain JSON properties with names that do not match
+                   a parameter that is defined in the template.
+                </para>
+             </wadl:doc>
+             </param>
+             <param xmlns="http://wadl.dev.java.net/2009/02" name="timeout_mins" style="plain"
+                required="false">
+             <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                xmlns:wadl="http://wadl.dev.java.net/2009/02"
+                xml:lang="EN">
+                <para>
+                   The timeout for stack creation in minutes.
+                </para>
+             </wadl:doc>
+             </param>
+          </representation>
+       </request>
+       <response status="200">
+           <representation mediaType="application/json">
+               <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                   xml:lang="EN">
+                   <xsdxt:code href="samples/stack_update_preview_resp.json"/>
+               </wadl:doc>
+           </representation>
+       </response>
+   </method>
    <method name="DELETE" id="stack_delete">
       <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
          title="Delete stack">
diff --git a/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_update_preview_resp.json b/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_update_preview_resp.json
new file mode 100644
index 000000000..9a511a178
--- /dev/null
+++ b/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_update_preview_resp.json
@@ -0,0 +1,67 @@
+{
+    "unchanged": [
+        {
+            "updated_time": "datetime",
+            "resource_name": "",
+            "physical_resource_id": "{resource id or ''}",
+            "resource_action": "CREATE",
+            "resource_status": "COMPLETE",
+            "resource_status_reason": "",
+            "resource_type": "restype",
+            "stack_identity": "{stack_id}",
+            "stack_name": "{stack_name}"
+        }
+    ],
+    "updated": [
+        {
+            "updated_time": "datetime",
+            "resource_name": "",
+            "physical_resource_id": "{resource id or ''}",
+            "resource_action": "CREATE",
+            "resource_status": "COMPLETE",
+            "resource_status_reason": "",
+            "resource_type": "restype",
+            "stack_identity": "{stack_id}",
+            "stack_name": "{stack_name}"
+        }
+    ],
+    "replaced": [
+        {
+            "updated_time": "datetime",
+            "resource_name": "",
+            "physical_resource_id": "{resource id or ''}",
+            "resource_action": "CREATE",
+            "resource_status": "COMPLETE",
+            "resource_status_reason": "",
+            "resource_type": "restype",
+            "stack_identity": "{stack_id}",
+            "stack_name": "{stack_name}"
+        }
+    ],
+    "added": [
+        {
+            "updated_time": "datetime",
+            "resource_name": "",
+            "physical_resource_id": "{resource id or ''}",
+            "resource_action": "CREATE",
+            "resource_status": "COMPLETE",
+            "resource_status_reason": "",
+            "resource_type": "restype",
+            "stack_identity": "{stack_id}",
+            "stack_name": "{stack_name}"
+        }
+    ],
+    "deleted": [
+        {
+            "updated_time": "datetime",
+            "resource_name": "",
+            "physical_resource_id": "{resource id or ''}",
+            "resource_action": "CREATE",
+            "resource_status": "COMPLETE",
+            "resource_status_reason": "",
+            "resource_type": "restype",
+            "stack_identity": "{stack_id}",
+            "stack_name": "{stack_name}"
+        }
+    ]
+}