From 51852ff91379e504c506174d7efe8d5d95c73668 Mon Sep 17 00:00:00 2001
From: Richard Lee <rblee88@gmail.com>
Date: Wed, 19 Feb 2014 11:10:35 -0600
Subject: [PATCH] Orchestration: Add preview stack docs

Co-Authored-By: Anderson Mesquita <andersonvom@gmail.com>
Change-Id: I97381b0d24627812e2c98048f9db8326cc719fae
Closes-Bug: #1282204
---
 api-ref/src/docbkx/ch_orchestration-v1.xml    |   4 +
 .../src/v1/orchestration-api.wadl             | 111 ++++++++++++++++++
 .../src/v1/samples/stack_preview.json         |  89 ++++++++++++++
 3 files changed, 204 insertions(+)
 create mode 100644 api-ref/src/wadls/orchestration-api/src/v1/samples/stack_preview.json

diff --git a/api-ref/src/docbkx/ch_orchestration-v1.xml b/api-ref/src/docbkx/ch_orchestration-v1.xml
index 33b0e760a..9a4153490 100644
--- a/api-ref/src/docbkx/ch_orchestration-v1.xml
+++ b/api-ref/src/docbkx/ch_orchestration-v1.xml
@@ -28,6 +28,10 @@
                 <wadl:method href="#stack_update"/>
                 <wadl:method href="#stack_delete"/>
             </wadl:resource>
+            <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#abandon">
                 <wadl:method href="#stack_abandon"/>
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 94883604f..770f45e97 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
@@ -26,6 +26,9 @@
                     <method href="#stack_create"/>
                     <method href="#stack_adopt"/>
                     <method href="#stack_list"/>
+                    <resource path="preview" id="preview">
+                        <method href="#stack_preview"/>
+                    </resource>
                     <resource path="{stack_name}" id="stack_name">
                         <param name="stack_name" style="template"
                             required="true">
@@ -272,6 +275,114 @@
         </request>
         <response status="201"/>
     </method>
+    <method name="POST" id="stack_preview">
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Preview stack">
+            <para role="shortdesc">Previews a stack.</para>
+        </wadl:doc>
+        <request>
+            <param name="stack_name" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The name of the stack to preview.</para>
+                </wadl:doc>
+            </param>
+            <param name="template_url" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        The URL of the template to instantiate. This
+                        value is ignored if the template is supplied
+                        inline.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="template" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        A JSON template to instantiate. This value
+                        takes precedence over the template URL if both
+                        are supplied.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="environment" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        A JSON environment for the stack.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="files" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        A map of file names (Provider resource
+                        templates, as referenced in the environment)
+                        to JSON template bodies.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="param_name-n" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        User-defined parameter names to pass to the
+                        template.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="param_value-n" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        User-defined parameter values to pass to the
+                        template.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="timeout_mins" style="plain" required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        The timeout for stack creation in minutes.
+                        During a stack preview, this value
+                        is only used as part of stack validation.
+                    </para>
+                </wadl:doc>
+            </param>
+            <param name="disable_rollback" style="plain"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>
+                        Controls whether a failure during stack
+                        creation causes deletion of all
+                        previously-created resources in that stack.
+                        The default is True; a failure does not cause
+                        deletions. During a stack preview, this value
+                        is only used as part of stack validation.
+                    </para>
+                </wadl:doc>
+            </param>
+            <representation mediaType="application/json">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <xsdxt:code href="samples/stack_create.json"/>
+                </wadl:doc>
+            </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_preview.json"/>
+                </wadl:doc>
+            </representation>
+        </response>
+    </method>
     <method name="POST" id="stack_adopt">
         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
             title="Adopt stack">
diff --git a/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_preview.json b/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_preview.json
new file mode 100644
index 000000000..7a2c79151
--- /dev/null
+++ b/api-ref/src/wadls/orchestration-api/src/v1/samples/stack_preview.json
@@ -0,0 +1,89 @@
+{
+    "stack": {
+        "id": "None",
+        "stack_name": "sample_stack",
+        "description": "Sample template description.",
+        "template_description": "Sample template description.",
+        "timeout_mins": 60,
+        "disable_rollback": true,
+        "capabilities": [],
+        "notification_topics": [],
+        "creation_time": "2014-02-19T16:04:56Z",
+        "updated_time": "2014-02-19T16:04:56Z",
+        "stack_status": "_",
+        "stack_status_reason": "",
+        "parameters": {
+            "AWS::Region": "ap-southeast-1",
+            "AWS::StackId": "arn:openstack:heat::2e327e5e7fa94b25a44be66fd9d1ec4d:stacks/sample_stack/None",
+            "AWS::StackName": "sample_stack",
+            "DBName": "wordpress",
+            "DBPassword": "******",
+            "DBRootPassword": "******",
+            "DBUsername": "******",
+            "InstanceType": "m1.small",
+            "KeyName": "heat_key",
+            "LinuxDistribution": "F17"
+        },
+        "links": [
+            {
+                "href": "http://10.0.2.15:8004/v1/2e327e5e7fa94b25a44be66fd9d1ec4d/stacks/sample_stack/None",
+                "rel": "self"
+            }
+        ],
+        "resources": [
+            {
+                "stack_name": "sample_stack",
+                "resource_name": "WikiDatabase-1",
+                "resource_type": "AWS::EC2::Instance",
+                "description": "",
+                "resource_action": "INIT",
+                "resource_status": "COMPLETE",
+                "resource_status_reason": "",
+                "physical_resource_id": "",
+                "required_by": [],
+                "resource_identity": {
+                    "path": "/resources/WikiDatabase-1",
+                    "stack_id": "None",
+                    "stack_name": "sample_stack",
+                    "tenant": "2e327e5e7fa94b25a44be66fd9d1ec4d"
+                },
+                "stack_identity": {
+                    "path": "",
+                    "stack_id": "None",
+                    "stack_name": "sample_stack",
+                    "tenant": "2e327e5e7fa94b25a44be66fd9d1ec4d"
+                },
+                "updated_time": "2014-02-19T16:04:56Z",
+                "metadata": {
+                    "AWS::CloudFormation::Init": {
+                        "config": {
+                            "packages": {
+                                "yum": {
+                                    "httpd": [],
+                                    "mysql": [],
+                                    "mysql-server": [],
+                                    "wordpress": []
+                                }
+                            },
+                            "services": {
+                                "systemd": {
+                                    "httpd": {
+                                        "enabled": "true",
+                                        "ensureRunning": "true"
+                                    },
+                                    "mysqld": {
+                                        "enabled": "true",
+                                        "ensureRunning": "true"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                "other resources...": "other resources..."
+            }
+        ]
+    }
+}