From 4170566618426960b0ac850ba8e41a5f73b95c5e Mon Sep 17 00:00:00 2001
From: Jay Dobies <jason.dobies@redhat.com>
Date: Wed, 4 May 2016 15:23:15 -0400
Subject: [PATCH] Migrate API documentations into the Heat tree

For more information, see:
http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html

This is the initial port from api-site. The includes in
source/v1/index.rst are alphabetized, but we may want to revisit that
and reorder them according to importance.

Change-Id: I6f578107e17d3a97e667f645a05493da12ae2048
Implements: blueprint api-doc-migration
---
 api-ref/ext/__init__.py                       |    0
 api-ref/ext/rest_parameters.py                |  377 ++++
 api-ref/source/conf.py                        |  224 +++
 api-ref/source/index.rst                      |   24 +
 api-ref/source/v1/build-info.inc              |   39 +
 api-ref/source/v1/general-info.inc            |   13 +
 api-ref/source/v1/heat-versions.inc           |   38 +
 api-ref/source/v1/index.rst                   |   32 +
 api-ref/source/v1/parameters.yaml             | 1580 +++++++++++++++++
 .../v1/samples/build-info-response.json       |    8 +
 .../v1/samples/config-create-request.json     |   28 +
 .../v1/samples/config-create-response.json    |   32 +
 .../v1/samples/config-show-response.json      |   32 +
 .../v1/samples/deployment-create-request.json |    8 +
 .../samples/deployment-create-response.json   |   14 +
 .../samples/deployment-metadata-response.json |  130 ++
 .../v1/samples/deployment-show-response.json  |   14 +
 .../v1/samples/deployment-update-request.json |   10 +
 .../samples/deployment-update-response.json   |   19 +
 .../v1/samples/deployments-list-response.json |   21 +
 .../v1/samples/event-show-response.json       |   33 +
 .../v1/samples/events-list-response.json      |   50 +
 .../v1/samples/heat-versions-response.json    |   14 +
 .../samples/resource-metadata-response.json   |    6 +
 .../v1/samples/resource-schema-response.json  |   30 +
 .../v1/samples/resource-show-response.json    |   27 +
 .../resource-type-template-response.json      |   50 +
 .../samples/resource-types-list-response.json |   61 +
 .../v1/samples/resources-list-response.json   |   25 +
 .../v1/samples/services-list-response.json    |   30 +
 .../v1/samples/stack-abandon-response.json    |   69 +
 .../stack-action-cancel-update-request.json   |    3 +
 .../samples/stack-action-check-request.json   |    3 +
 .../samples/stack-action-resume-request.json  |    3 +
 .../samples/stack-action-suspend-request.json |    3 +
 .../v1/samples/stack-adopt-request.json       |   33 +
 .../v1/samples/stack-create-request.json      |   32 +
 .../v1/samples/stack-create-response.json     |   11 +
 .../v1/samples/stack-find-response.json       |   27 +
 .../samples/stack-outputs-list-response.json  |   10 +
 .../v1/samples/stack-preview-response.json    |  168 ++
 .../samples/stack-show-output-response.json   |    8 +
 .../v1/samples/stack-show-response.json       |   32 +
 .../samples/stack-show-snapshot-response.json |   47 +
 .../v1/samples/stack-snapshot-request.json    |    3 +
 .../v1/samples/stack-snapshot-response.json   |    8 +
 .../stack-snapshots-list-response.json        |   12 +
 .../stack-update-preview-response.json        |   67 +
 .../v1/samples/stack-update-request.json      |   28 +
 .../v1/samples/stacks-list-response.json      |   20 +
 .../v1/samples/template-show-response.json    |   28 +
 .../v1/samples/template-validate-request.json |    3 +
 .../samples/template-validate-response.json   |   41 +
 .../samples/template-versions-response.json   |   32 +
 api-ref/source/v1/service-status.inc          |   67 +
 api-ref/source/v1/software-config.inc         |  416 +++++
 api-ref/source/v1/stack-actions.inc           |  173 ++
 api-ref/source/v1/stack-events.inc            |  155 ++
 api-ref/source/v1/stack-resources.inc         |  191 ++
 api-ref/source/v1/stack-templates.inc         |  300 ++++
 api-ref/source/v1/stacks.inc                  |  818 +++++++++
 tox.ini                                       |   18 +
 62 files changed, 5798 insertions(+)
 create mode 100644 api-ref/ext/__init__.py
 create mode 100644 api-ref/ext/rest_parameters.py
 create mode 100644 api-ref/source/conf.py
 create mode 100644 api-ref/source/index.rst
 create mode 100644 api-ref/source/v1/build-info.inc
 create mode 100644 api-ref/source/v1/general-info.inc
 create mode 100644 api-ref/source/v1/heat-versions.inc
 create mode 100644 api-ref/source/v1/index.rst
 create mode 100644 api-ref/source/v1/parameters.yaml
 create mode 100644 api-ref/source/v1/samples/build-info-response.json
 create mode 100644 api-ref/source/v1/samples/config-create-request.json
 create mode 100644 api-ref/source/v1/samples/config-create-response.json
 create mode 100644 api-ref/source/v1/samples/config-show-response.json
 create mode 100644 api-ref/source/v1/samples/deployment-create-request.json
 create mode 100644 api-ref/source/v1/samples/deployment-create-response.json
 create mode 100644 api-ref/source/v1/samples/deployment-metadata-response.json
 create mode 100644 api-ref/source/v1/samples/deployment-show-response.json
 create mode 100644 api-ref/source/v1/samples/deployment-update-request.json
 create mode 100644 api-ref/source/v1/samples/deployment-update-response.json
 create mode 100644 api-ref/source/v1/samples/deployments-list-response.json
 create mode 100644 api-ref/source/v1/samples/event-show-response.json
 create mode 100644 api-ref/source/v1/samples/events-list-response.json
 create mode 100644 api-ref/source/v1/samples/heat-versions-response.json
 create mode 100644 api-ref/source/v1/samples/resource-metadata-response.json
 create mode 100644 api-ref/source/v1/samples/resource-schema-response.json
 create mode 100644 api-ref/source/v1/samples/resource-show-response.json
 create mode 100644 api-ref/source/v1/samples/resource-type-template-response.json
 create mode 100644 api-ref/source/v1/samples/resource-types-list-response.json
 create mode 100644 api-ref/source/v1/samples/resources-list-response.json
 create mode 100644 api-ref/source/v1/samples/services-list-response.json
 create mode 100644 api-ref/source/v1/samples/stack-abandon-response.json
 create mode 100644 api-ref/source/v1/samples/stack-action-cancel-update-request.json
 create mode 100644 api-ref/source/v1/samples/stack-action-check-request.json
 create mode 100644 api-ref/source/v1/samples/stack-action-resume-request.json
 create mode 100644 api-ref/source/v1/samples/stack-action-suspend-request.json
 create mode 100644 api-ref/source/v1/samples/stack-adopt-request.json
 create mode 100644 api-ref/source/v1/samples/stack-create-request.json
 create mode 100644 api-ref/source/v1/samples/stack-create-response.json
 create mode 100644 api-ref/source/v1/samples/stack-find-response.json
 create mode 100644 api-ref/source/v1/samples/stack-outputs-list-response.json
 create mode 100644 api-ref/source/v1/samples/stack-preview-response.json
 create mode 100644 api-ref/source/v1/samples/stack-show-output-response.json
 create mode 100644 api-ref/source/v1/samples/stack-show-response.json
 create mode 100644 api-ref/source/v1/samples/stack-show-snapshot-response.json
 create mode 100644 api-ref/source/v1/samples/stack-snapshot-request.json
 create mode 100644 api-ref/source/v1/samples/stack-snapshot-response.json
 create mode 100644 api-ref/source/v1/samples/stack-snapshots-list-response.json
 create mode 100644 api-ref/source/v1/samples/stack-update-preview-response.json
 create mode 100644 api-ref/source/v1/samples/stack-update-request.json
 create mode 100644 api-ref/source/v1/samples/stacks-list-response.json
 create mode 100644 api-ref/source/v1/samples/template-show-response.json
 create mode 100644 api-ref/source/v1/samples/template-validate-request.json
 create mode 100644 api-ref/source/v1/samples/template-validate-response.json
 create mode 100644 api-ref/source/v1/samples/template-versions-response.json
 create mode 100644 api-ref/source/v1/service-status.inc
 create mode 100644 api-ref/source/v1/software-config.inc
 create mode 100644 api-ref/source/v1/stack-actions.inc
 create mode 100644 api-ref/source/v1/stack-events.inc
 create mode 100644 api-ref/source/v1/stack-resources.inc
 create mode 100644 api-ref/source/v1/stack-templates.inc
 create mode 100644 api-ref/source/v1/stacks.inc

diff --git a/api-ref/ext/__init__.py b/api-ref/ext/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/api-ref/ext/rest_parameters.py b/api-ref/ext/rest_parameters.py
new file mode 100644
index 0000000000..88e7513434
--- /dev/null
+++ b/api-ref/ext/rest_parameters.py
@@ -0,0 +1,377 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""This provides a sphinx extension able to create the HTML needed
+for the api-ref website.
+
+It contains 2 new stanzas.
+
+  .. rest_method:: GET /foo/bar
+
+Which is designed to be used as the first stanza in a new section to
+state that section is about that REST method. During processing the
+rest stanza will be reparented to be before the section in question,
+and used as a show/hide selector for it's details.
+
+  .. rest_parameters:: file.yaml
+
+     - name1: name_in_file1
+     - name2: name_in_file2
+     - name3: name_in_file3
+
+Which is designed to build structured tables for either response or
+request parameters. The stanza takes a value which is a file to lookup
+details about the parameters in question.
+
+The contents of the stanza are a yaml list of key / value pairs. The
+key is the name of the parameter to be shown in the table. The value
+is the key in the file.yaml where all other metadata about the
+parameter will be extracted. This allows for reusing parameter
+definitions widely in API definitions, but still providing for control
+in both naming and ordering of parameters at every declaration.
+
+"""
+
+from docutils import nodes
+from docutils.parsers.rst.directives.tables import Table
+from docutils.statemachine import ViewList
+from sphinx.util.compat import Directive
+
+import yaml
+
+
+def full_name(cls):
+    return cls.__module__ + '.' + cls.__name__
+
+
+class rest_method(nodes.Part, nodes.Element):
+    """rest_method custom node type
+
+    We specify a custom node type for rest_method so that we can
+    accumulate all the data about the rest method, but not render as
+    part of the normal rendering process. This means that we need a
+    renderer for every format we wish to support with this.
+
+    """
+    pass
+
+
+class rest_expand_all(nodes.Part, nodes.Element):
+    pass
+
+
+class RestExpandAllDirective(Directive):
+    has_content = True
+
+    def run(self):
+        return [rest_expand_all()]
+
+
+class RestMethodDirective(Directive):
+
+    # this enables content in the directive
+    has_content = True
+
+    def run(self):
+        lineno = self.state_machine.abs_line_number()
+        target = nodes.target()
+        section = nodes.section(classes=["detail-control"])
+        # env = self.state.document.settings.env
+        # env.app.info("Parent %s" % self.state.parent.attributes)
+
+        node = rest_method()
+
+        # TODO(sdague): this is a super simplistic parser, should be
+        # more robust.
+        method, sep, url = self.content[0].partition(' ')
+
+        node['method'] = method
+        node['url'] = url
+        node['target'] = self.state.parent.attributes['ids'][0]
+
+        # We need to build a temporary target that we can replace
+        # later in the processing to get the TOC to resolve correctly.
+        temp_target = "%s-selector" % node['target']
+        target = nodes.target(ids=[temp_target])
+        self.state.add_target(temp_target, '', target, lineno)
+        section += node
+
+        return [target, section]
+
+
+class RestParametersDirective(Table):
+
+    headers = ["Name", "In", "Type", "Description"]
+
+    def yaml_from_file(self, fpath):
+        """Collect Parameter stanzas from inline + file.
+
+        This allows use to reference an external file for the actual
+        parameter definitions.
+        """
+        # self.app.info("Fpath: %s" % fpath)
+        try:
+            with open(fpath, 'r') as stream:
+                lookup = yaml.load(stream)
+        except IOError:
+            self.env.warn(
+                self.env.docname,
+                "Parameters file %s not found" % fpath)
+            return
+        except yaml.YAMLError as exc:
+            self.app.warn(exc)
+            raise
+
+        content = "\n".join(self.content)
+        parsed = yaml.load(content)
+        # self.app.info("Params loaded is %s" % parsed)
+        # self.app.info("Lookup table looks like %s" % lookup)
+        new_content = list()
+        for paramlist in parsed:
+            for name, ref in paramlist.items():
+                if ref in lookup:
+                    new_content.append((name, lookup[ref]))
+                else:
+                    # TODO(sdague): this provides a kind of confusing
+                    # error message because env.warn isn't meant to be
+                    # used this way, however it does provide a way to
+                    # track down where the parameters list is that is
+                    # wrong. So it's good enough for now.
+                    self.env.warn(
+                        "%s:%s " % (
+                            self.state_machine.node.source,
+                            self.state_machine.node.line),
+                        ("No field definition for ``%s`` found in ``%s``. "
+                         " Skipping." % (ref, fpath)))
+
+        # self.app.info("New content %s" % new_content)
+        self.yaml = new_content
+
+    def run(self):
+        self.env = self.state.document.settings.env
+        self.app = self.env.app
+
+        # Make sure we have some content, which should be yaml that
+        # defines some parameters.
+        if not self.content:
+            error = self.state_machine.reporter.error(
+                'No parameters defined',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            return [error]
+
+        if not len(self.arguments) >= 1:
+            self.state_machine.reporter.error(
+                'No reference file defined',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            return [error]
+
+        # NOTE(sdague): it's important that we pop the arg otherwise
+        # we end up putting the filename as the table caption.
+        rel_fpath, fpath = self.env.relfn2path(self.arguments.pop())
+        self.yaml_file = fpath
+        self.yaml_from_file(self.yaml_file)
+
+        self.max_cols = len(self.headers)
+        # TODO(sdague): it would be good to dynamically set column
+        # widths (or basically make the colwidth thing go away
+        # entirely)
+        self.options['widths'] = (20, 10, 10, 60)
+        self.col_widths = self.get_column_widths(self.max_cols)
+        # Actually convert the yaml
+        title, messages = self.make_title()
+        # self.app.info("Title %s, messages %s" % (title, messages))
+        table_node = self.build_table()
+        self.add_name(table_node)
+        if title:
+            table_node.insert(0, title)
+        return [table_node] + messages
+
+    def get_rows(self, table_data):
+        rows = []
+        groups = []
+        trow = nodes.row()
+        entry = nodes.entry()
+        para = nodes.paragraph(text=unicode(table_data))
+        entry += para
+        trow += entry
+        rows.append(trow)
+        return rows, groups
+
+        # Add a column for a field. In order to have the RST inside
+    # these fields get rendered, we need to use the
+    # ViewList. Note, ViewList expects a list of lines, so chunk
+    # up our content as a list to make it happy.
+    def add_col(self, value):
+        entry = nodes.entry()
+        result = ViewList(value.split('\n'))
+        self.state.nested_parse(result, 0, entry)
+        return entry
+
+    def show_no_yaml_error(self):
+        trow = nodes.row(classes=["no_yaml"])
+        trow += self.add_col("No yaml found %s" % self.yaml_file)
+        trow += self.add_col("")
+        trow += self.add_col("")
+        trow += self.add_col("")
+        return trow
+
+    def collect_rows(self):
+        rows = []
+        groups = []
+        try:
+            # self.app.info("Parsed content is: %s" % self.yaml)
+            for key, values in self.yaml:
+                min_version = values.get('min_version', '')
+                desc = values.get('description', '')
+                classes = []
+                if min_version:
+                    desc += ("\n\n**New in version %s**\n" % min_version)
+                    min_ver_css_name = ("rp_min_ver_" +
+                                        str(min_version).replace('.', '_'))
+                    classes.append(min_ver_css_name)
+                trow = nodes.row(classes=classes)
+                name = key
+                if values.get('required', False) is False:
+                    name += " (Optional)"
+                trow += self.add_col(name)
+                trow += self.add_col(values.get('in'))
+                trow += self.add_col(values.get('type'))
+                trow += self.add_col(desc)
+                rows.append(trow)
+        except AttributeError as exc:
+            if 'key' in locals():
+                self.app.warn("Failure on key: %s, values: %s. %s" %
+                              (key, values, exc))
+            else:
+                rows.append(self.show_no_yaml_error())
+        return rows, groups
+
+    def build_table(self):
+        table = nodes.table()
+        tgroup = nodes.tgroup(cols=len(self.headers))
+        table += tgroup
+
+        # TODO(sdague): it would be really nice to figure out how not
+        # to have this stanza, it kind of messes up all of the table
+        # formatting because it doesn't let tables just be the right
+        # size.
+        tgroup.extend(
+             nodes.colspec(colwidth=col_width, colname='c' + str(idx))
+             for idx, col_width in enumerate(self.col_widths)
+        )
+
+        thead = nodes.thead()
+        tgroup += thead
+
+        row_node = nodes.row()
+        thead += row_node
+        row_node.extend(nodes.entry(h, nodes.paragraph(text=h))
+                        for h in self.headers)
+
+        tbody = nodes.tbody()
+        tgroup += tbody
+
+        rows, groups = self.collect_rows()
+        tbody.extend(rows)
+        table.extend(groups)
+
+        return table
+
+
+def rest_method_html(self, node):
+    tmpl = """
+<div class="row operation-grp">
+    <div class="col-md-1 operation">
+    <a name="%(target)s" class="operation-anchor" href="#%(target)s">
+      <span class="glyphicon glyphicon-link"></span></a>
+    <span class="label label-success">%(method)s</span>
+    </div>
+    <div class="col-md-5">%(url)s</div>
+    <div class="col-md-5">%(desc)s</div>
+    <div class="col-md-1">
+    <button
+       class="btn btn-info btn-sm btn-detail"
+       data-target="#%(target)s-detail"
+       data-toggle="collapse"
+       id="%(target)s-detail-btn"
+       >detail</button>
+    </div>
+</div>"""
+
+    self.body.append(tmpl % node)
+    raise nodes.SkipNode
+
+
+def rest_expand_all_html(self, node):
+    tmpl = """
+<div>
+<div class=col-md-11></div>
+<div class=col-md-1>
+    <button id="expand-all"
+       data-toggle="collapse"
+       class="btn btn-info btn-sm btn-expand-all"
+    >Show All</button>
+</div>
+</div>"""
+
+    self.body.append(tmpl % node)
+    raise nodes.SkipNode
+
+
+def resolve_rest_references(app, doctree):
+    for node in doctree.traverse():
+        if isinstance(node, rest_method):
+            rest_node = node
+            rest_method_section = node.parent
+            rest_section = rest_method_section.parent
+            gp = rest_section.parent
+
+            # Added required classes to the top section
+            rest_section.attributes['classes'].append('api-detail')
+            rest_section.attributes['classes'].append('collapse')
+
+            # Pop the title off the collapsed section
+            title = rest_section.children.pop(0)
+            rest_node['desc'] = title.children[0]
+
+            # In order to get the links in the sidebar to be right, we
+            # have to do some id flipping here late in the game. The
+            # rest_method_section has basically had a dummy id up
+            # until this point just to keep it from colliding with
+            # it's parent.
+            rest_section.attributes['ids'][0] = (
+                "%s-detail" % rest_section.attributes['ids'][0])
+            rest_method_section.attributes['ids'][0] = rest_node['target']
+
+            # Pop the overall section into it's grand parent,
+            # right before where the current parent lives
+            idx = gp.children.index(rest_section)
+            rest_section.remove(rest_method_section)
+            gp.insert(idx, rest_method_section)
+
+
+def setup(app):
+    app.add_node(rest_method,
+                 html=(rest_method_html, None))
+    app.add_node(rest_expand_all,
+                 html=(rest_expand_all_html, None))
+    app.add_directive('rest_parameters', RestParametersDirective)
+    app.add_directive('rest_method', RestMethodDirective)
+    app.add_directive('rest_expand_all', RestExpandAllDirective)
+    app.add_stylesheet('bootstrap.min.css')
+    app.add_stylesheet('api-site.css')
+    app.add_javascript('bootstrap.min.js')
+    app.add_javascript('api-site.js')
+    app.connect('doctree-read', resolve_rest_references)
+    return {'version': '0.1'}
diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py
new file mode 100644
index 0000000000..0a2eb9f878
--- /dev/null
+++ b/api-ref/source/conf.py
@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# heat documentation build config file, copied from:
+# nova documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+import warnings
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+extensions = [
+    'ext.rest_parameters',
+    'oslosphinx',
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Orchestration API Reference'
+copyright = u'2010-present, OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+from heat.version import version_info
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+# The short X.Y version.
+version = version_info.version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+    "-n1"]
+try:
+    html_last_updated_fmt = subprocess.Popen(
+        git_cmd, stdout=subprocess.PIPE).communicate()[0]
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'heatdoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index', 'Heat.tex', u'OpenStack Orchestration API Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True
+
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
new file mode 100644
index 0000000000..e537344363
--- /dev/null
+++ b/api-ref/source/index.rst
@@ -0,0 +1,24 @@
+..
+      Copyright 2010 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+==========================
+Orchestration Service APIs
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   v1/index
diff --git a/api-ref/source/v1/build-info.inc b/api-ref/source/v1/build-info.inc
new file mode 100644
index 0000000000..3236228b0a
--- /dev/null
+++ b/api-ref/source/v1/build-info.inc
@@ -0,0 +1,39 @@
+.. -*- rst -*-
+
+==========
+Build info
+==========
+
+
+
+
+Show build information
+======================
+
+.. rest_method::  GET /v1/{tenant_id}/build_info
+
+Shows build information for an Orchestration deployment.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/build-info-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/v1/general-info.inc b/api-ref/source/v1/general-info.inc
new file mode 100644
index 0000000000..6efdb58b95
--- /dev/null
+++ b/api-ref/source/v1/general-info.inc
@@ -0,0 +1,13 @@
+.. -*- rst -*-
+
+=======================
+General API information
+=======================
+
+Authenticated calls that target a known URI but that use an HTTP
+method that the implementation does not support return a ``405
+Method Not Allowed`` error code. In addition, the HTTP ``OPTIONS``
+method is supported for each known URI. In both cases, the
+``Allow`` response header indicates the HTTP methods that are
+supported for the resource.
+
diff --git a/api-ref/source/v1/heat-versions.inc b/api-ref/source/v1/heat-versions.inc
new file mode 100644
index 0000000000..bef1b4568b
--- /dev/null
+++ b/api-ref/source/v1/heat-versions.inc
@@ -0,0 +1,38 @@
+.. -*- rst -*-
+
+============
+API versions
+============
+
+
+
+
+List versions
+=============
+
+.. rest_method::  GET /
+
+Lists all Orchestration API versions.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/heat-versions-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst
new file mode 100644
index 0000000000..9f609c2556
--- /dev/null
+++ b/api-ref/source/v1/index.rst
@@ -0,0 +1,32 @@
+..
+      Copyright 2010 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+:tocdepth: 2
+
+============================
+Orchestration Service API v1
+============================
+
+.. include:: build-info.inc
+.. include:: general-info.inc
+.. include:: heat-versions.inc
+.. include:: service-status.inc
+.. include:: software-config.inc
+.. include:: stack-actions.inc
+.. include:: stack-events.inc
+.. include:: stack-resources.inc
+.. include:: stack-templates.inc
+.. include:: stacks.inc
diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml
new file mode 100644
index 0000000000..9f8b42c1d9
--- /dev/null
+++ b/api-ref/source/v1/parameters.yaml
@@ -0,0 +1,1580 @@
+# variables in header
+
+# variables in path
+config_id:
+  description: |
+    The UUID of the configuration.
+  in: path
+  required: false
+  type: string
+deployment_id:
+  description: |
+    The UUID of the deployment.
+  in: path
+  required: false
+  type: string
+event_id:
+  description: |
+    The UUID of the event that is related to the
+    resource in the stack.
+  in: path
+  required: false
+  type: string
+output_key_1:
+  description: |
+    The key of a stack output.
+  in: path
+  required: false
+  type: string
+resource_name:
+  description: |
+    The name of a resource in the stack.
+  in: path
+  required: false
+  type: string
+server_id_2:
+  description: |
+    The UUID of the server for which to fetch
+    configuration metadata.
+  in: path
+  required: false
+  type: string
+snapshot_id:
+  description: |
+    The UUID of the snapshot.
+  in: path
+  required: false
+  type: string
+stack_id:
+  description: |
+    The UUID of the stack.
+  in: path
+  required: false
+  type: string
+stack_name:
+  description: |
+    The name of a stack.
+  in: path
+  required: false
+  type: string
+tenant_id:
+  description: |
+    The UUID of the tenant. A tenant is also known as
+    an account or project.
+  in: path
+  required: false
+  type: string
+type_name:
+  description: |
+    The name of a resource type.
+  in: path
+  required: false
+  type: string
+
+# variables in query
+action_3:
+  description: |
+    Filters the stack list by an action. Use this
+    filter multiple times to filter by multiple actions.
+  in: query
+  required: false
+  type: string
+global_tenant:
+  description: |
+    Set to ``true`` to include stacks from all
+    tenants in the stack list. Specify policy requirements in the
+    Orchestration ``policy.json`` file. Default is ``false``.
+  in: query
+  required: false
+  type: boolean
+id_4:
+  description: |
+    Filters the stack list by a stack ID. Use this
+    filter multiple times to filter by multiple IDs.
+  in: query
+  required: false
+  type: string
+limit:
+  description: |
+    Requests a page size of items. Returns a number
+    of items up to a limit value. Use the ``limit`` parameter to make
+    an initial limited request and use the ID of the last-seen item
+    from the response as the ``marker`` parameter value in a
+    subsequent limited request.
+  in: query
+  required: false
+  type: integer
+marker:
+  description: |
+    The ID of the last-seen item. Use the ``limit``
+    parameter to make an initial limited request and use the ID of the
+    last-seen item from the response as the ``marker`` parameter value
+    in a subsequent limited request.
+  in: query
+  required: false
+  type: string
+name:
+  description: |
+    Filters the response by a resource type name. You
+    can set this value to a regular expression. Use this filter
+    multiple times to filter by multiple names.
+  in: query
+  required: false
+  type: string
+name_4:
+  description: |
+    Filters the stack list by a name. Use this filter
+    multiple times to filter by multiple names.
+  in: query
+  required: false
+  type: string
+nested_depth:
+  description: |
+    Includes resources from nested stacks up to the
+    ``nested_depth`` levels of recursion.
+  in: query
+  required: false
+  type: integer
+not_tags:
+  description: |
+    Lists stacks that do not contain one or more
+    simple string tags. To specify multiple tags, separate the tags
+    with commas. For example, ``tag1,tag2``. The boolean AND
+    expression is used to combine multiple tags.
+  in: query
+  required: false
+  type: string
+not_tags_any:
+  description: |
+    Lists stacks that do not contain one or more
+    simple string tags. To specify multiple tags, separate the tags
+    with commas. For example, ``tag1,tag2``. The boolean OR expression
+    is used to combine multiple tags.
+  in: query
+  required: false
+  type: string
+owner_id:
+  description: |
+    Filters the stack list by an owner ID, which is
+    the ID of the parent stack of listed stack. Use this filter
+    multiple times to filter by multiple owner IDs.
+  in: query
+  required: false
+  type: string
+resource_action:
+  description: |
+    Filters the event list by a resource action. You
+    can use this filter multiple times to filter by multiple resource
+    actions. Valid resource actions are ``ADOPT``, ``CHECK``,
+    ``CREATE``, ``DELETE``, ``INIT``, ``RESTORE``, ``RESUME``,
+    ``ROLLBACK``, ``SNAPSHOT``, ``SUSPEND``, and ``UPDATE``.
+  in: query
+  required: false
+  type: string
+resource_name_2:
+  description: |
+    Filters the event list by a resource name. You
+    can use this filter multiple times to filter by multiple resource
+    names.
+  in: query
+  required: false
+  type: string
+resource_status:
+  description: |
+    Filters the event list by a resource status. You
+    can use this filter multiple times to filter by multiple resource
+    statuses. Valid resource statuses are ``COMPLETE``, ``FAILED``,
+    and ``IN_PROGRESS``.
+  in: query
+  required: false
+  type: string
+resource_type:
+  description: |
+    Filters the event list by a resource type. You
+    can use this filter multiple times to filter by multiple resource
+    types. Valid resource types include ``OS::Cinder::Volume``,
+    ``OS::Nova::Server``, ``OS::Neutron::Port``, and so on.
+  in: query
+  required: false
+  type: string
+show_deleted:
+  description: |
+    Set to ``true`` to include deleted stacks in the
+    list. Default is ``false``, which excludes deleted stacks from the
+    list.
+  in: query
+  required: false
+  type: boolean
+show_nested:
+  description: |
+    Set to ``true`` to include nested stacks in the
+    list. Default is ``false``, which excludes nested stacks from the
+    list.
+  in: query
+  required: false
+  type: boolean
+sort_dir:
+  description: |
+    The sort direction of the list. A valid value is
+    ``asc`` (ascending) or ``desc`` (descending).
+  in: query
+  required: false
+  type: string
+sort_keys:
+  description: |
+    Sorts the list by the ``resource_type`` or
+    ``created_at`` key.
+  in: query
+  required: false
+  type: string
+sort_keys_1:
+  description: |
+    Sorts the stack list by ``stack_name``,
+    ``stack_status``, ``creation_time``, or ``updated_time`` key.
+  in: query
+  required: false
+  type: string
+status_5:
+  description: |
+    Filters the stack list by a status. Use this
+    filter multiple times to filter by multiple statuses.
+  in: query
+  required: false
+  type: string
+support_status_1:
+  description: |
+    Filters the response by resource types by a
+    support status. Valid support status values are ``UNKNOWN``,
+    ``SUPPORTED``, ``DEPRECATED``, ``UNSUPPORTED``, and ``HIDDEN``.
+    Use this filter multiple times to filter by multiple support
+    statuses.
+  in: query
+  required: false
+  type: string
+tags_1:
+  description: |
+    Lists stacks that contain one or more simple
+    string tags. To specify multiple tags, separate the tags with
+    commas. For example, ``tag1,tag2``. The boolean AND expression is
+    used to combine multiple tags.
+  in: query
+  required: false
+  type: string
+tags_any:
+  description: |
+    Lists stacks that contain one or more simple
+    string tags. To specify multiple tags, separate the tags with
+    commas. For example, ``tag1,tag2``. The boolean OR expression is
+    used to combine multiple tags.
+  in: query
+  required: false
+  type: string
+tenant:
+  description: |
+    Filters the stack list by a tenant. Use this
+    filter multiple times to filter by multiple tenants.
+  in: query
+  required: false
+  type: string
+username:
+  description: |
+    Filters the stack list by a user name. Use this
+    filter multiple times to filter by multiple user names.
+  in: query
+  required: false
+  type: string
+version:
+  description: |
+    Filters the response by resource types by heat
+    version. For example, ``2016.1`` or ``5.0.0``. Use this filter
+    multiple times to filter by multiple versions.
+  in: query
+  required: false
+  type: string
+with_count:
+  description: |
+    Set to ``true`` to include a count key in the
+    response. The count key value is the number of stacks that match
+    the query criteria. Default is ``false``.
+  in: query
+  required: false
+  type: boolean
+with_detail:
+  description: |
+    Enables detailed resource information for each
+    resource in list of resources.
+  in: query
+  required: false
+  type: boolean
+
+# variables in body
+Description:
+  description: |
+    The description specified in the template.
+  in: body
+  required: true
+  type: string
+HeatTemplateFormatVersion:
+  description: |
+    The version of the heat template.
+  in: body
+  required: true
+  type: string
+Outputs:
+  description: |
+    Key and value pairs that contain output data.
+  in: body
+  required: true
+  type: object
+ParameterGroups:
+  description: |
+    A list of parameter groups. Each group contains a
+    list of parameter names.
+  in: body
+  required: false
+  type: array
+Parameters:
+  description: |
+    Key and value pairs that contain template
+    parameters.
+  in: body
+  required: true
+  type: object
+Parameters_1:
+  description: |
+    An object that defines all input parameters that
+    are defined in the template. Indexed by parameter name.
+  in: body
+  required: true
+  type: object
+Resources:
+  description: |
+    Contain ``KeyPair`` for resource template.
+  in: body
+  required: true
+  type: object
+action:
+  description: |
+    The current stack action that triggers this
+    deployment resource.
+  in: body
+  required: true
+  type: string
+action_1:
+  description: |
+    The deployment action.
+  in: body
+  required: true
+  type: string
+action_2:
+  description: |
+    Current stack action in which this deployment
+    resource is being triggered.
+  in: body
+  required: true
+  type: string
+adopt_stack_data:
+  description: |
+    Existing resources data to adopt a stack. Data
+    returned by abandon stack could be provided as
+    ``adopt_stack_data``.
+  in: body
+  required: true
+  type: object
+attributes:
+  description: |
+    Key and value pairs that contain resource
+    attributes.
+  in: body
+  required: true
+  type: object
+binary:
+  description: |
+    The name of the binary form of the heat engine.
+  in: body
+  required: true
+  type: string
+cancel_update:
+  description: |
+    Specify the ``cancel_update`` action in the
+    request body.
+  in: body
+  required: true
+  type: string
+capabilities:
+  description: |
+    List of stack capabilities for stack.
+  in: body
+  required: true
+  type: array
+capabilities_1:
+  description: |
+    A list of stack capabilities.
+  in: body
+  required: true
+  type: array
+check:
+  description: |
+    Specify the ``check`` action in the request body.
+  in: body
+  required: true
+  type: string
+config:
+  description: |
+    Configuration script or manifest that defines
+    which configuration is performed.
+  in: body
+  required: false
+  type: string
+config_1:
+  description: |
+    The configuration code.
+  in: body
+  required: true
+  type: string
+config_id_1:
+  description: |
+    The UUID of the software configuration resource
+    that runs when applying to the server.
+  in: body
+  required: true
+  type: string
+config_id_2:
+  description: |
+    The UUID of the configuration.
+  in: body
+  required: true
+  type: string
+config_id_3:
+  description: |
+    The UUID of the software configuration resource
+    to run when applying to the server. This UUID might not be the
+    same configuration UUID with which the deployment was created
+    because ephemeral configurations are created throughout the life
+    cycle of the deployment.
+  in: body
+  required: true
+  type: string
+created_at:
+  description: |
+    The date and time when the resource was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time:
+  description: |
+    The date and time when the stack resource was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time_1:
+  description: |
+    The date and time when the software was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time_2:
+  description: |
+    The date and time when the resource was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time_3:
+  description: |
+    The date and time when the snapshot was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time_4:
+  description: |
+    The date and time when the software was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2016-03-30T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+creation_time_5:
+  description: |
+    The date and time when the stack was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+  in: body
+  required: true
+  type: string
+data:
+  description: |
+    The snapshot data.
+  in: body
+  required: true
+  type: object
+deleted_at:
+  description: |
+    The date and time when the resource was deleted.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+  in: body
+  required: true
+  type: string
+description:
+  description: |
+    The description of the stack resource.
+  in: body
+  required: true
+  type: string
+description_1:
+  description: |
+    The description of the resource attribute.
+  in: body
+  required: true
+  type: string
+description_2:
+  description: |
+    The description of a stack output.
+  in: body
+  required: true
+  type: string
+description_3:
+  description: |
+    The description of the active stack.
+  in: body
+  required: true
+  type: string
+description_4:
+  description: |
+    A description of the stack.
+  in: body
+  required: true
+  type: string
+description_5:
+  description: |
+    The description of the stack.
+  in: body
+  required: true
+  type: string
+description_6:
+  description: |
+    The description of the stack template.
+  in: body
+  required: true
+  type: string
+disable_rollback:
+  description: |
+    Enables or disables deletion of all stack
+    resources when stack creation fails. Set to ``true`` to keep all
+    resources when stack creation fails. Set to ``false`` to delete
+    all resources when stack creation fails. Default is ``true``.
+  in: body
+  required: false
+  type: boolean
+disable_rollback_1:
+  description: |
+    Enables or disables deletion of all previously-
+    created stack resources when stack creation fails. Set to ``true``
+    to keep all previously-created stack resources when stack creation
+    fails. Set to ``false`` to delete all previously-created stack
+    resources when stack creation fails. Default is ``true``.
+  in: body
+  required: false
+  type: boolean
+disable_rollback_2:
+  description: |
+    Enables or disables stack rollback when stack
+    creation fails. Set to ``true`` to rollback the stack when stack
+    creation fails. Set to ``false`` to disable stack rollback when
+    stack creation fails. Default is ``true``.
+  in: body
+  required: true
+  type: boolean
+environment:
+  description: |
+    A JSON environment for the stack.
+  in: body
+  required: false
+  type: object
+files:
+  description: |
+    Supplies the contents of files referenced in the template or the
+    environment. Stack templates and resource templates can explicitly
+    reference files by using the ``get_file`` intrinsic function. In
+    addition, the ``environment`` parameter can contain implicit
+    references to files.
+
+    The value is a JSON object, where each key is a relative or
+    absolute URI which serves as the name of a file, and the associated
+    value provides the contents of the file. The following code shows
+    the general structure of this parameter.
+
+    .. code-block:: json
+
+       { ...
+           "files": {
+               "fileA.yaml": "Contents of the file",
+               "file:///usr/fileB.template": "Contents of the file",
+               "http://example.com/fileC.template": "Contents of the file"
+           }
+       ...
+       }
+
+    Additionally, some template authors encode their user data in a
+    local file. The Orchestration client examines the template for the
+    ``get_file`` intrinsic function and adds an entry to the ``files``
+    map with the path to the file as the name and the file contents as
+    the value. So, a simple example looks like this:
+
+    .. code-block:: json
+
+       {
+          "files": {
+             "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt"
+          },
+          ...,
+          "stack_name": "teststack",
+          "template": {
+             ...,
+             "resources": {
+                "my_server": {
+                   "type": "OS::Nova::Server",
+                   "properties": {
+                      ...,
+                      "user_data": {
+                         "get_file": "myfile"
+                      }
+                   }
+                }
+             }
+          },
+          "timeout_mins": 60
+       }
+
+    Do not use this parameter to provide the content of the template
+    located at the ``template_url`` address. Instead, use the
+    ``template`` parameter to supply the template content as part of
+    the request.
+  in: body
+  required: false
+  type: object
+group:
+  description: |
+    Namespace that groups this software configuration
+    by when it is delivered to a server. This setting might simply
+    define which configuration tool performs the configuration.
+  in: body
+  required: false
+  type: string
+group_1:
+  description: |
+    The name of the group in which the software is
+    configured.
+  in: body
+  required: true
+  type: string
+heat_template_version:
+  description: |
+    The version of the heat template.
+  in: body
+  required: true
+  type: string
+hostname:
+  description: |
+    The name of the host for the service.
+  in: body
+  required: true
+  type: string
+id:
+  description: |
+    The UUID of the heat engine.
+  in: body
+  required: true
+  type: string
+id_1:
+  description: |
+    The UUID of the software deployment.
+  in: body
+  required: true
+  type: string
+id_2:
+  description: |
+    The UUID of the system-assigned stack.
+  in: body
+  required: true
+  type: string
+id_3:
+  description: |
+    The UUID of the snapshot.
+  in: body
+  required: true
+  type: string
+id_5:
+  description: |
+    The UUID of the stack.
+  in: body
+  required: true
+  type: string
+input_values:
+  description: |
+    A list of input data.
+  in: body
+  required: true
+  type: array
+inputs:
+  description: |
+    Schema that represents the inputs that this
+    software configuration expects.
+  in: body
+  required: false
+  type: array
+inputs_1:
+  description: |
+    A list of inputs to configure the software.
+  in: body
+  required: true
+  type: array
+links:
+  description: |
+    A list of URLs for the stack. Each URL is a JSON
+    object with an ``href`` key indicating the URL and a ``rel`` key
+    indicating its relationship to the stack in question. There may be
+    multiple links returned. The ``self`` relationship identifies the
+    URL of the stack itself.
+  in: body
+  required: true
+  type: array
+links_1:
+  description: |
+    A list of stack links.
+  in: body
+  required: true
+  type: array
+logical_resource_id:
+  description: |
+    The ID of the logical stack resource.
+  in: body
+  required: true
+  type: string
+name_1:
+  description: |
+    The name of the configuration to create.
+  in: body
+  required: false
+  type: string
+name_2:
+  description: |
+    The name of the software configuration.
+  in: body
+  required: true
+  type: string
+name_3:
+  description: |
+    The name of the snapshot.
+  in: body
+  required: true
+  type: string
+notification_topics:
+  description: |
+    List of notification topics for stack.
+  in: body
+  required: true
+  type: array
+notification_topics_1:
+  description: |
+    A list of stack notifications.
+  in: body
+  required: true
+  type: array
+options:
+  description: |
+    Map that contains options that are specific to
+    the configuration management tool that this resource uses.
+  in: body
+  required: false
+  type: string
+options_1:
+  description: |
+    The options, if any, to include in the code. For
+    example any dependent flags.
+  in: body
+  required: true
+  type: string
+output_error:
+  description: |
+    The error in a stack output.
+  in: body
+  required: true
+  type: string
+output_key:
+  description: |
+    The name of a stack output.
+  in: body
+  required: true
+  type: string
+output_value:
+  description: |
+    The value of a stack output.
+  in: body
+  required: true
+  type: string
+output_values:
+  description: |
+    A list of output data.
+  in: body
+  required: true
+  type: array
+output_values_1:
+  description: |
+    Map of output values for the deployment, as
+    signaled from the server.
+  in: body
+  required: false
+  type: object
+outputs:
+  description: |
+    Schema that represents the outputs that this
+    software configuration produces.
+  in: body
+  required: false
+  type: array
+outputs_1:
+  description: |
+    A list of software configuration output data.
+  in: body
+  required: true
+  type: array
+outputs_2:
+  description: |
+    A list of stack outputs.
+  in: body
+  required: true
+  type: array
+outputs_3:
+  description: |
+    Key and value pairs that contain output data.
+  in: body
+  required: true
+  type: object
+parameters:
+  description: |
+    Supplies arguments for parameters defined in the stack template.
+
+    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, ``a`` and ``b`` would be the names of two
+    parameters defined in the template.
+
+    .. code-block:: json
+
+       { ...
+           "parameters": {
+               "a": "Value",
+               "b": "3"
+           }
+       ...
+       }
+
+    While the service accepts JSON numbers for parameters with the type
+    ``number`` and JSON objects for parameters with the type ``json``,
+    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.
+
+    A value must be provided for each template parameter which does not
+    specify a default value. However, this parameter is not allowed to
+    contain JSON properties with names that do not match a parameter
+    defined in the template.
+
+    The ``files`` parameter maps logical file names to file contents.
+    Both the ``get_file`` intrinsic function and provider template
+    functionality use this mapping. When you want to use a provider
+    template, for example, the Orchestration service adds an entry to
+    the ``files`` map by using:
+
+    - The URL of the provider template as the name.
+
+    - The contents of that file as the value.
+
+    Additionally, some template authors encode their user data in a
+    local file. The Orchestration client examines the template for the
+    ``get_file`` intrinsic function and adds an entry to the ``files``
+    map with the path to the file as the name and the file contents as
+    the value. So, a simple example looks like this:
+
+    .. code-block:: json
+
+       {
+          "files": {
+             "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt"
+          },
+          ...,
+          "stack_name": "teststack",
+          "template": {
+             ...,
+             "resources": {
+                "my_server": {
+                   "type": "OS::Nova::Server",
+                   "properties": {
+                      ...,
+                      "user_data": {
+                         "get_file": "myfile"
+                      }
+                   }
+                }
+             }
+          },
+          "timeout_mins": 60
+       }
+  in: body
+  required: false
+  type: object
+parameters_1:
+  description: |
+    Key and value pairs that contain stack
+    parameters.
+  in: body
+  required: true
+  type: object
+parameters_2:
+  description: |
+    Key and value pairs that contain template
+    parameters.
+  in: body
+  required: true
+  type: object
+parameters_3:
+  description: "Supplies updated arguments for parameters that are defined in the\n\
+    stack template.\n\nThe value is a JSON object, where each key is the name of a\n\
+    parameter defined in the template and the associated value is the\nargument to\
+    \ use for that parameter when instantiating the template.\nThe following code\
+    \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\
+    \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\
+    \ json\n\n   { ...\n                         \"parameters\": {\n             \
+    \            \"a\": \"Value\",\n                         \"b\": \"3\"\n      \
+    \                   }\n                         ... }\n                     \n\
+    \nWhile the service accepts JSON numbers for parameters with the type\n``number``\
+    \ and JSON objects for parameters with the type ``json``,\nall parameter values\
+    \ are converted to their string representation\nfor storage in the created Stack.\
+    \ Clients are encouraged to send\nall parameter values using their string representation\
+    \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\
+    \nYou must specify a value for each template parameter that does not\nhave a default\
+    \ value. However, this parameter cannot contain JSON\nproperties with names that\
+    \ do not match a parameter that is defined\nin the template.\n"
+  in: body
+  required: false
+  type: object
+parameters_4:
+  description: "This parameter supplies updated arguments for parameters defined in\n\
+    the stack template.\n\nThe value is a JSON object, where each key is the name\
+    \ of a\nparameter defined in the template and the associated value is the\nargument\
+    \ to use for that parameter when instantiating the template.\nThe following code\
+    \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\
+    \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\
+    \ json\n\n   { ...\n                        \"parameters\": {\n              \
+    \          \"a\": \"Value\",\n                        \"b\": \"3\"\n         \
+    \               }\n                        ... }\n                  \n\nWhile\
+    \ the service accepts JSON numbers for parameters with the type\n``number`` and\
+    \ JSON objects for parameters with the type ``json``,\nall parameter values are\
+    \ converted to their string representation\nfor storage in the created Stack.\
+    \ Clients are encouraged to send\nall parameter values using their string representation\
+    \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\
+    \nYou must specify a value for each template parameter that does not\nhave a default\
+    \ value. However, this parameter cannot contain JSON\nproperties with names that\
+    \ do not match a parameter that is defined\nin the template.\n"
+  in: body
+  required: false
+  type: object
+parent:
+  description: |
+    The stack ID of the parent stack, if this is a
+    nested stack.
+  in: body
+  required: true
+  type: string
+parent_1:
+  description: |
+    The parent of the stack.
+  in: body
+  required: true
+  type: string
+physical_resource_id:
+  description: |
+    The ID of the stack physical resource.
+  in: body
+  required: true
+  type: string
+project_id:
+  description: |
+    The UUID of the project.
+  in: body
+  required: true
+  type: string
+properties:
+  description: |
+    The properties of the resource. Includes
+    description, type, and so on.
+  in: body
+  required: true
+  type: object
+report_interval:
+  description: |
+    The polling interval, in seconds. The API reports
+    events at this interval until heat engine creation completes.
+  in: body
+  required: true
+  type: integer
+required:
+  description: |
+    If set to ``true`` the attribute is required.
+  in: body
+  required: true
+  type: boolean
+required_by:
+  description: |
+    The list of resources that require this stack
+    resource.
+  in: body
+  required: true
+  type: array
+resource:
+  description: |
+    Key and value pairs that contain stack resource
+    properties.
+  in: body
+  required: true
+  type: object
+resource_name_1:
+  description: |
+    The name of the resource.
+  in: body
+  required: true
+  type: string
+resource_status_1:
+  description: |
+    The status of the resource.
+  in: body
+  required: true
+  type: string
+resource_status_reason:
+  description: |
+    The reason for the current stack resource state.
+  in: body
+  required: true
+  type: string
+resource_type_1:
+  description: |
+    The type of the resource.
+  in: body
+  required: true
+  type: string
+resources:
+  description: |
+    A list of resources and their properties.
+  in: body
+  required: true
+  type: array
+resources_1:
+  description: |
+    List of stack resources.
+  in: body
+  required: true
+  type: array
+resources_2:
+  description: |
+    The snapshot resources.
+  in: body
+  required: true
+  type: object
+resources_3:
+  description: |
+    The required sources for creating the stack
+    template.
+  in: body
+  required: true
+  type: object
+resume:
+  description: |
+    Specify the ``resume`` action in the request
+    body.
+  in: body
+  required: true
+  type: string
+server_id:
+  description: |
+    The UUID of the compute server to which the
+    configuration applies.
+  in: body
+  required: true
+  type: string
+server_id_1:
+  description: |
+    The UUID of the server.
+  in: body
+  required: true
+  type: string
+services:
+  description: |
+    A list of heat engines.
+  in: body
+  required: true
+  type: array
+snapshot:
+  description: |
+    Key and value pairs that contain snapshot
+    properties.
+  in: body
+  required: true
+  type: object
+snapshots:
+  description: |
+    A list of snapshots and their properties.
+  in: body
+  required: true
+  type: array
+stack:
+  description: |
+    The ``stack`` object.
+  in: body
+  required: true
+  type: object
+stack_name_1:
+  description: |
+    A name for the new stack.  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
+    ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression.  When you delete
+    or abandon a stack, its name will not become available for reuse
+    until the deletion completes successfully.
+  in: body
+  required: true
+  type: string
+stack_name_2:
+  description: |
+    A name for the new stack.  This 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
+    ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression.  When you delete
+    or abandon a stack, its name will not become available for reuse
+    until the deletion completes successfully.
+  in: body
+  required: true
+  type: string
+stack_name_3:
+  description: |
+    The name of the active stack.
+  in: body
+  required: true
+  type: string
+stack_owner:
+  description: |
+    Stack owner name.
+  in: body
+  required: true
+  type: string
+stack_owner_1:
+  description: |
+    The owner of the stack.
+  in: body
+  required: true
+  type: string
+stack_status:
+  description: |
+    The status of the active stack.
+  in: body
+  required: true
+  type: string
+stack_status_1:
+  description: |
+    The status of the stack.
+  in: body
+  required: true
+  type: string
+stack_status_reason:
+  description: |
+    The reason for the current status of the stack.
+  in: body
+  required: true
+  type: string
+stack_user_project_id:
+  description: |
+    Authentication project ID, which can also perform
+    operations on this deployment.
+  in: body
+  required: false
+  type: string
+stack_user_project_id_1:
+  description: |
+    The project UUID of the stack user.
+  in: body
+  required: true
+  type: string
+status:
+  description: |
+    The status of the heat engine.
+  in: body
+  required: true
+  type: string
+status_1:
+  description: |
+    Current status of the deployment. A valid value
+    is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``.
+  in: body
+  required: false
+  type: string
+status_2:
+  description: |
+    The status of the software deployment. The value
+    is ``INPROGRESS`` or ``COMPLETE``.
+  in: body
+  required: true
+  type: string
+status_3:
+  description: |
+    Current status of the deployment. Value is
+    ``IN_PROGRESS``, ``COMPLETE``, or ``FAILED``.
+  in: body
+  required: false
+  type: string
+status_4:
+  description: |
+    The status of the snapshot.
+  in: body
+  required: true
+  type: string
+status_reason:
+  description: |
+    Error description for the last status change,
+    which is ``FAILED`` status.
+  in: body
+  required: false
+  type: string
+status_reason_1:
+  description: |
+    The debug information for the current status.
+  in: body
+  required: true
+  type: string
+status_reason_2:
+  description: |
+    The reason for the current snapshot status.
+  in: body
+  required: true
+  type: string
+support_status:
+  description: |
+    Information about the current status.
+  in: body
+  required: true
+  type: object
+suspend:
+  description: |
+    Specify the ``suspend`` action in the request
+    body.
+  in: body
+  required: true
+  type: string
+tags:
+  description: |
+    One or more simple string tags to associate with
+    the stack. To associate multiple tags with a stack, separate the
+    tags with commas. For example, ``tag1,tag2``.
+  in: body
+  required: false
+  type: string
+tags_2:
+  description: |
+    The stack tags.
+  in: body
+  required: true
+  type: string
+template:
+  description: |
+    The stack template on which to perform the operation.
+
+    This parameter is always provided as a ``string`` in the JSON
+    request body. The content of the string is a JSON- or YAML-
+    formatted Orchestration template. For example:
+
+    .. code-block:: json
+
+       "template": {
+           "heat_template_version": "2013-05-23",
+           ...}
+
+    This parameter is required only when you omit the ``template_url``
+    parameter. If you specify both parameters, this value overrides the
+    ``template_url`` parameter value.
+  in: body
+  required: true
+  type: object
+template_1:
+  description: |
+    Information about the template.
+  in: body
+  required: true
+  type: object
+template_2:
+  description: |
+    The stack template on which to perform the operation.
+
+    This parameter is always provided as a ``string`` in the JSON
+    request body. The content of the string is a JSON- or YAML-
+    formatted Orchestration template. For example:
+
+    .. code-block:: json
+
+       "template": {
+           "heat_template_version": "2013-05-23",
+           ...}
+
+    This parameter is required only when you omit the ``template_url``
+    parameter. If you specify both parameters, this value overrides the
+    ``template_url`` parameter value.
+  in: body
+  required: false
+  type: object
+template_description:
+  description: |
+    A description of the template that defines the
+    stack.
+  in: body
+  required: true
+  type: string
+template_description_1:
+  description: |
+    The description of the stack template.
+  in: body
+  required: true
+  type: string
+template_url:
+  description: |
+    A URI to the location containing the stack
+    template on which to perform the operation.  See the description
+    of the ``template`` parameter for information about the expected
+    template content located at the URI.  This parameter is only
+    required when you omit the ``template`` parameter. If you specify
+    both parameters, this parameter is ignored.
+  in: body
+  required: false
+  type: string
+timeout_mins:
+  description: |
+    The timeout for stack creation in minutes.
+  in: body
+  required: false
+  type: integer
+timeout_mins_1:
+  description: |
+    Time-lines for stack creation.
+  in: body
+  required: true
+  type: integer
+timeout_mins_2:
+  description: |
+    The timeout, in minutes.
+  in: body
+  required: true
+  type: string
+topic:
+  description: |
+    The topic of the heat engine.
+  in: body
+  required: true
+  type: string
+type:
+  description: |
+    The property type.
+  in: body
+  required: true
+  type: string
+update_allowed:
+  description: |
+    If set to ``true``, update is allowed.
+  in: body
+  required: true
+  type: boolean
+updated_at:
+  description: |
+    The date and time when the resource was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: true
+  type: string
+updated_time:
+  description: |
+    The date and time when the stack resource was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: true
+  type: string
+updated_time_1:
+  description: |
+    The date and time when the stack resource was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2016-03-30T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: true
+  type: string
+updated_time_2:
+  description: |
+    Time of last stack update in the following
+    format: ``YYYY-MM- DDThh:mm:ssTZD``, where ``TZD`` is the time
+    zone designator.
+  in: body
+  required: true
+  type: string
+updated_time_3:
+  description: |
+    The date and time when the stack was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    If the ``updated_at`` date and time stamp is not set, its value is
+    ``null``.
+  in: body
+  required: true
+  type: string
+
diff --git a/api-ref/source/v1/samples/build-info-response.json b/api-ref/source/v1/samples/build-info-response.json
new file mode 100644
index 0000000000..650200f887
--- /dev/null
+++ b/api-ref/source/v1/samples/build-info-response.json
@@ -0,0 +1,8 @@
+{
+    "api": {
+        "revision": "{api_build_revision}"
+    },
+    "engine": {
+        "revision": "{engine_build_revision}"
+    }
+}
diff --git a/api-ref/source/v1/samples/config-create-request.json b/api-ref/source/v1/samples/config-create-request.json
new file mode 100644
index 0000000000..d9f44241b8
--- /dev/null
+++ b/api-ref/source/v1/samples/config-create-request.json
@@ -0,0 +1,28 @@
+{
+    "inputs": [
+        {
+            "default": null,
+            "type": "String",
+            "name": "foo",
+            "description": null
+        },
+        {
+            "default": null,
+            "type": "String",
+            "name": "bar",
+            "description": null
+        }
+    ],
+    "group": "script",
+    "name": "a-config-we5zpvyu7b5o",
+    "outputs": [
+        {
+            "type": "String",
+            "name": "result",
+            "error_output": false,
+            "description": null
+        }
+    ],
+    "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
+    "options": null
+}
diff --git a/api-ref/source/v1/samples/config-create-response.json b/api-ref/source/v1/samples/config-create-response.json
new file mode 100644
index 0000000000..5025435b92
--- /dev/null
+++ b/api-ref/source/v1/samples/config-create-response.json
@@ -0,0 +1,32 @@
+{
+    "software_config": {
+        "creation_time": "2015-01-31T15:12:36Z",
+        "inputs": [
+            {
+                "default": null,
+                "type": "String",
+                "name": "foo",
+                "description": null
+            },
+            {
+                "default": null,
+                "type": "String",
+                "name": "bar",
+                "description": null
+            }
+        ],
+        "group": "script",
+        "name": "a-config-we5zpvyu7b5o",
+        "outputs": [
+            {
+                "type": "String",
+                "name": "result",
+                "error_output": false,
+                "description": null
+            }
+        ],
+        "options": null,
+        "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
+        "id": "ddee7aca-aa32-4335-8265-d436b20db4f1"
+    }
+}
diff --git a/api-ref/source/v1/samples/config-show-response.json b/api-ref/source/v1/samples/config-show-response.json
new file mode 100644
index 0000000000..e89b2b1c09
--- /dev/null
+++ b/api-ref/source/v1/samples/config-show-response.json
@@ -0,0 +1,32 @@
+{
+    "software_config": {
+        "inputs": [
+            {
+                "default": null,
+                "type": "String",
+                "name": "foo",
+                "description": null
+            },
+            {
+                "default": null,
+                "type": "String",
+                "name": "bar",
+                "description": null
+            }
+        ],
+        "group": "script",
+        "name": "a-config-we5zpvyu7b5o",
+        "outputs": [
+            {
+                "type": "String",
+                "name": "result",
+                "error_output": false,
+                "description": null
+            }
+        ],
+        "creation_time": "2015-01-31T15:12:36Z",
+        "id": "ddee7aca-aa32-4335-8265-d436b20db4f1",
+        "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
+        "options": null
+    }
+}
diff --git a/api-ref/source/v1/samples/deployment-create-request.json b/api-ref/source/v1/samples/deployment-create-request.json
new file mode 100644
index 0000000000..92ad840690
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-create-request.json
@@ -0,0 +1,8 @@
+{
+    "status": "IN_PROGRESS",
+    "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+    "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
+    "stack_user_project_id": "c024bfada67845ddb17d2b0c0be8cd79",
+    "action": "CREATE",
+    "status_reason": "Deploy data available"
+}
diff --git a/api-ref/source/v1/samples/deployment-create-response.json b/api-ref/source/v1/samples/deployment-create-response.json
new file mode 100644
index 0000000000..736f1e15bf
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-create-response.json
@@ -0,0 +1,14 @@
+{
+    "software_deployment": {
+        "status": "IN_PROGRESS",
+        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+        "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
+        "output_values": null,
+        "input_values": null,
+        "action": "CREATE",
+        "status_reason": "Deploy data available",
+        "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8",
+        "creation_time": "2015-01-31T15:12:36Z",
+        "updated_time": "2015-01-31T15:18:21Z"
+    }
+}
diff --git a/api-ref/source/v1/samples/deployment-metadata-response.json b/api-ref/source/v1/samples/deployment-metadata-response.json
new file mode 100644
index 0000000000..8c5bd9a9dc
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-metadata-response.json
@@ -0,0 +1,130 @@
+{
+    "metadata": [
+        {
+            "inputs": [
+                {
+                    "default": null,
+                    "type": "String",
+                    "name": "foo",
+                    "value": "fooooo",
+                    "description": null
+                },
+                {
+                    "default": null,
+                    "type": "String",
+                    "name": "bar",
+                    "value": "baaaaa",
+                    "description": null
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_server_id",
+                    "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+                    "description": "ID of the server being deployed to"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_action",
+                    "value": "CREATE",
+                    "description": "Name of the current action being deployed"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_stack_id",
+                    "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc",
+                    "description": "ID of the stack this deployment belongs to"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_resource_name",
+                    "value": "deployment",
+                    "description": "Name of this deployment resource in the stack"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_signal_id",
+                    "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fdeployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=ca3571413e4a49998d580215517b3685&SignatureVersion=2&Signature=w6Iu%2BNbg86mqwSOUf1GLuKPO7KaD82PiGpL4ig9Q1l4%3D",
+                    "description": "ID of signal to use for signalling output values"
+                }
+            ],
+            "group": "script",
+            "name": "a-config-we5zpvyu7b5o",
+            "outputs": [
+                {
+                    "type": "String",
+                    "name": "result",
+                    "error_output": false,
+                    "description": null
+                }
+            ],
+            "options": null,
+            "creation_time": "2015-01-31T15:12:36Z",
+            "updated_time": "2015-01-31T15:18:21Z",
+            "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
+            "id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434"
+        },
+        {
+            "inputs": [
+                {
+                    "default": null,
+                    "type": "String",
+                    "name": "foo",
+                    "value": "fu",
+                    "description": null
+                },
+                {
+                    "default": null,
+                    "type": "String",
+                    "name": "bar",
+                    "value": "barmy",
+                    "description": null
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_server_id",
+                    "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+                    "description": "ID of the server being deployed to"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_action",
+                    "value": "CREATE",
+                    "description": "Name of the current action being deployed"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_stack_id",
+                    "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc",
+                    "description": "ID of the stack this deployment belongs to"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_resource_name",
+                    "value": "other_deployment",
+                    "description": "Name of this deployment resource in the stack"
+                },
+                {
+                    "type": "String",
+                    "name": "deploy_signal_id",
+                    "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fother_deployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=7b761482f8254946bcd3d5ccb36fe939&SignatureVersion=2&Signature=giMfv%2BhrAw6y%2FCMKQIQz2IhO5PkAj5%2BfP5YsL6rul3o%3D",
+                    "description": "ID of signal to use for signalling output values"
+                }
+            ],
+            "group": "script",
+            "name": "a-config-we5zpvyu7b5o",
+            "outputs": [
+                {
+                    "type": "String",
+                    "name": "result",
+                    "error_output": false,
+                    "description": null
+                }
+            ],
+            "options": null,
+            "creation_time": "2015-01-31T16:14:13Z",
+            "updated_time": "2015-01-31T16:18:19Z",
+            "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
+            "id": "8da95794-2ad9-4979-8ae5-739ce314c5cd"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/deployment-show-response.json b/api-ref/source/v1/samples/deployment-show-response.json
new file mode 100644
index 0000000000..b234235acd
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-show-response.json
@@ -0,0 +1,14 @@
+{
+    "software_deployment": {
+        "status": "IN_PROGRESS",
+        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+        "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434",
+        "output_values": null,
+        "input_values": null,
+        "action": "CREATE",
+        "status_reason": "Deploy data available",
+        "id": "06e87bcc-33a2-4bce-aebd-533e698282d3",
+        "creation_time": "2015-01-31T15:12:36Z",
+        "updated_time": "2015-01-31T15:18:21Z"
+    }
+}
diff --git a/api-ref/source/v1/samples/deployment-update-request.json b/api-ref/source/v1/samples/deployment-update-request.json
new file mode 100644
index 0000000000..a9877f5887
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-update-request.json
@@ -0,0 +1,10 @@
+{
+    "status": "COMPLETE",
+    "output_values": {
+        "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n",
+        "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n",
+        "deploy_status_code": 0,
+        "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
+    },
+    "status_reason": "Outputs received"
+}
diff --git a/api-ref/source/v1/samples/deployment-update-response.json b/api-ref/source/v1/samples/deployment-update-response.json
new file mode 100644
index 0000000000..19b7bbfec7
--- /dev/null
+++ b/api-ref/source/v1/samples/deployment-update-response.json
@@ -0,0 +1,19 @@
+{
+    "software_deployment": {
+        "status": "COMPLETE",
+        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+        "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434",
+        "output_values": {
+            "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n",
+            "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n",
+            "deploy_status_code": 0,
+            "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
+        },
+        "input_values": null,
+        "action": "CREATE",
+        "status_reason": "Outputs received",
+        "id": "06e87bcc-33a2-4bce-aebd-533e698282d3",
+        "creation_time": "2015-01-31T15:12:36Z",
+        "updated_time": "2015-01-31T15:18:21Z"
+    }
+}
diff --git a/api-ref/source/v1/samples/deployments-list-response.json b/api-ref/source/v1/samples/deployments-list-response.json
new file mode 100644
index 0000000000..95b783c554
--- /dev/null
+++ b/api-ref/source/v1/samples/deployments-list-response.json
@@ -0,0 +1,21 @@
+{
+    "software_deployments": [
+        {
+            "status": "COMPLETE",
+            "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
+            "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
+            "output_values": {
+                "deploy_stdout": "Writing to /tmp/barmy\nWritten to /tmp/barmy\n",
+                "deploy_stderr": "+ echo Writing to /tmp/barmy\n+ echo fu\n+ cat /tmp/barmy\n+ echo -n The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/barmy\n+ echo Output to stderr\nOutput to stderr\n",
+                "deploy_status_code": 0,
+                "result": "The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
+            },
+            "input_values": null,
+            "action": "CREATE",
+            "status_reason": "Outputs received",
+            "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8",
+            "creation_time": "2015-01-31T15:12:36Z",
+            "updated_time": "2015-01-31T15:18:21Z"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/event-show-response.json b/api-ref/source/v1/samples/event-show-response.json
new file mode 100644
index 0000000000..3631e8ac3e
--- /dev/null
+++ b/api-ref/source/v1/samples/event-show-response.json
@@ -0,0 +1,33 @@
+{
+    "event": {
+        "event_time": "2015-06-25T14:59:53",
+        "id": "8db23e2e-72b2-47a2-9ed9-b52417f56e50",
+        "links": [
+            {
+                "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name/events/8db23e2e-72b2-47a2-9ed9-b52417f56e50",
+                "rel": "self"
+            },
+            {
+                "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name",
+                "rel": "resource"
+            },
+            {
+                "href": "http://hostname/v1/1234/stacks/mystack/56789",
+                "rel": "stack"
+            }
+        ],
+        "logical_resource_id": "random_key_name",
+        "physical_resource_id": null,
+        "resource_name": "random_key_name",
+        "resource_properties": {
+            "character_classes": null,
+            "character_sequences": null,
+            "length": 8,
+            "salt": null,
+            "sequence": null
+        },
+        "resource_status": "CREATE_IN_PROGRESS",
+        "resource_status_reason": "state changed",
+        "resource_type": "OS::Heat::RandomString"
+    }
+}
diff --git a/api-ref/source/v1/samples/events-list-response.json b/api-ref/source/v1/samples/events-list-response.json
new file mode 100644
index 0000000000..83d8f88c4c
--- /dev/null
+++ b/api-ref/source/v1/samples/events-list-response.json
@@ -0,0 +1,50 @@
+{
+    "events": [
+        {
+            "resource_name": "port",
+            "event_time": "2014-07-23T08:14:47Z",
+            "links": [
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/474bfdf0-a450-46ec-a78a-0c7faa404073",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
+                    "rel": "resource"
+                },
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
+                    "rel": "stack"
+                }
+            ],
+            "logical_resource_id": "port",
+            "resource_status": "CREATE_FAILED",
+            "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found",
+            "physical_resource_id": null,
+            "id": "474bfdf0-a450-46ec-a78a-0c7faa404073"
+        },
+        {
+            "resource_name": "port",
+            "event_time": "2014-07-23T08:14:47Z",
+            "links": [
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
+                    "rel": "resource"
+                },
+                {
+                    "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
+                    "rel": "stack"
+                }
+            ],
+            "logical_resource_id": "port",
+            "resource_status": "CREATE_IN_PROGRESS",
+            "resource_status_reason": "state changed",
+            "physical_resource_id": null,
+            "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/heat-versions-response.json b/api-ref/source/v1/samples/heat-versions-response.json
new file mode 100644
index 0000000000..e13cf94f30
--- /dev/null
+++ b/api-ref/source/v1/samples/heat-versions-response.json
@@ -0,0 +1,14 @@
+{
+    "versions": [
+        {
+            "status": "CURRENT",
+            "id": "v1.0",
+            "links": [
+                {
+                    "href": "http://23.253.228.211:8000/v1/",
+                    "rel": "self"
+                }
+            ]
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/resource-metadata-response.json b/api-ref/source/v1/samples/resource-metadata-response.json
new file mode 100644
index 0000000000..7f1860ce86
--- /dev/null
+++ b/api-ref/source/v1/samples/resource-metadata-response.json
@@ -0,0 +1,6 @@
+{
+    "metadata": {
+        "some_key": "some_value",
+        "some_other_key": "some_other_value"
+    }
+}
diff --git a/api-ref/source/v1/samples/resource-schema-response.json b/api-ref/source/v1/samples/resource-schema-response.json
new file mode 100644
index 0000000000..9f930f1fd2
--- /dev/null
+++ b/api-ref/source/v1/samples/resource-schema-response.json
@@ -0,0 +1,30 @@
+{
+    "attributes": {
+        "an_attribute": {
+            "description": "A runtime value of the resource."
+        }
+    },
+    "properties": {
+        "a_property": {
+            "constraints": [
+                {
+                    "description": "Must be between 1 and 255 characters",
+                    "length": {
+                        "max": 255,
+                        "min": 1
+                    }
+                }
+            ],
+            "description": "A resource description.",
+            "required": true,
+            "type": "string",
+            "update_allowed": false
+        }
+    },
+    "resource_type": "OS::Heat::AResourceName",
+    "support_status": {
+        "message": "A status message",
+        "status": "SUPPORTED",
+        "version": "2014.1"
+    }
+}
diff --git a/api-ref/source/v1/samples/resource-show-response.json b/api-ref/source/v1/samples/resource-show-response.json
new file mode 100644
index 0000000000..6062ab2db5
--- /dev/null
+++ b/api-ref/source/v1/samples/resource-show-response.json
@@ -0,0 +1,27 @@
+{
+    "resource": {
+        "attributes": {
+            "value": "I9S20uIp"
+        },
+        "creation_time": "2015-06-25T14:59:53",
+        "description": "",
+        "links": [
+            {
+                "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name",
+                "rel": "self"
+            },
+            {
+                "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c",
+                "rel": "stack"
+            }
+        ],
+        "logical_resource_id": "random_key_name",
+        "physical_resource_id": "mystack-random_key_name-pmjmy5pks735",
+        "required_by": [],
+        "resource_name": "random_key_name",
+        "resource_status": "CREATE_COMPLETE",
+        "resource_status_reason": "state changed",
+        "resource_type": "OS::Heat::RandomString",
+        "updated_time": "2015-06-25T14:59:53"
+    }
+}
diff --git a/api-ref/source/v1/samples/resource-type-template-response.json b/api-ref/source/v1/samples/resource-type-template-response.json
new file mode 100644
index 0000000000..13cc0f5cc8
--- /dev/null
+++ b/api-ref/source/v1/samples/resource-type-template-response.json
@@ -0,0 +1,50 @@
+{
+    "HeatTemplateFormatVersion": "2012-12-12",
+    "Outputs": {
+        "private_key": {
+            "Description": "The private key if it has been saved.",
+            "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"private_key\"]}"
+        },
+        "public_key": {
+            "Description": "The public key.",
+            "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"public_key\"]}"
+        }
+    },
+    "Parameters": {
+        "name": {
+            "Description": "The name of the key pair.",
+            "Type": "String"
+        },
+        "public_key": {
+            "Description": "The optional public key. This allows users to supply the public key from a pre-existing key pair. If not supplied, a new key pair will be generated.",
+            "Type": "String"
+        },
+        "save_private_key": {
+            "AllowedValues": [
+                true,
+                "true",
+                false,
+                "false"
+            ],
+            "Default": false,
+            "Description": "true if the system should remember a generated private key; false otherwise.",
+            "Type": "String"
+        }
+    },
+    "Resources": {
+        "KeyPair": {
+            "Properties": {
+                "name": {
+                    "Ref": "name"
+                },
+                "public_key": {
+                    "Ref": "public_key"
+                },
+                "save_private_key": {
+                    "Ref": "save_private_key"
+                }
+            },
+            "Type": "OS::Nova::KeyPair"
+        }
+    }
+}
diff --git a/api-ref/source/v1/samples/resource-types-list-response.json b/api-ref/source/v1/samples/resource-types-list-response.json
new file mode 100644
index 0000000000..f9cbef5d6c
--- /dev/null
+++ b/api-ref/source/v1/samples/resource-types-list-response.json
@@ -0,0 +1,61 @@
+{
+    "resource_types": [
+        "AWS::EC2::Instance",
+        "OS::Heat::ScalingPolicy",
+        "AWS::CloudFormation::Stack",
+        "OS::Keystone::Group",
+        "OS::Glance::Image",
+        "AWS::EC2::Volume",
+        "OS::Heat::SoftwareDeployment",
+        "AWS::AutoScaling::ScalingPolicy",
+        "AWS::EC2::InternetGateway",
+        "OS::Heat::SoftwareDeployments",
+        "AWS::EC2::VolumeAttachment",
+        "AWS::CloudFormation::WaitConditionHandle",
+        "OS::Cinder::VolumeAttachment",
+        "OS::Cinder::EncryptedVolumeType",
+        "OS::Heat::AutoScalingGroup",
+        "OS::Nova::FloatingIP",
+        "OS::Heat::HARestarter",
+        "OS::Keystone::Project",
+        "OS::Keystone::Endpoint",
+        "OS::Heat::InstanceGroup",
+        "AWS::CloudWatch::Alarm",
+        "AWS::AutoScaling::AutoScalingGroup",
+        "OS::Heat::CloudConfig",
+        "OS::Heat::SoftwareComponent",
+        "OS::Cinder::Volume",
+        "OS::Keystone::Service",
+        "OS::Heat::WaitConditionHandle",
+        "OS::Heat::SoftwareConfig",
+        "AWS::CloudFormation::WaitCondition",
+        "OS::Heat::StructuredDeploymentGroup",
+        "OS::Heat::RandomString",
+        "OS::Heat::SoftwareDeploymentGroup",
+        "OS::Nova::KeyPair",
+        "OS::Heat::MultipartMime",
+        "OS::Heat::UpdateWaitConditionHandle",
+        "OS::Nova::Server",
+        "AWS::IAM::AccessKey",
+        "AWS::EC2::SecurityGroup",
+        "AWS::EC2::EIPAssociation",
+        "AWS::EC2::EIP",
+        "OS::Heat::AccessPolicy",
+        "AWS::IAM::User",
+        "OS::Heat::WaitCondition",
+        "OS::Heat::StructuredDeployment",
+        "AWS::RDS::DBInstance",
+        "AWS::AutoScaling::LaunchConfiguration",
+        "OS::Heat::Stack",
+        "OS::Nova::FloatingIPAssociation",
+        "OS::Heat::ResourceGroup",
+        "OS::Heat::StructuredConfig",
+        "OS::Nova::ServerGroup",
+        "OS::Heat::StructuredDeployments",
+        "OS::Keystone::Role",
+        "OS::Keystone::User",
+        "AWS::ElasticLoadBalancing::LoadBalancer",
+        "OS::Nova::Flavor",
+        "OS::Cinder::VolumeType"
+    ]
+}
diff --git a/api-ref/source/v1/samples/resources-list-response.json b/api-ref/source/v1/samples/resources-list-response.json
new file mode 100644
index 0000000000..5df952ca04
--- /dev/null
+++ b/api-ref/source/v1/samples/resources-list-response.json
@@ -0,0 +1,25 @@
+{
+    "resources": [
+        {
+            "creation_time": "2015-06-25T14:59:53",
+            "links": [
+                {
+                    "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name",
+                    "rel": "self"
+                },
+                {
+                    "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c",
+                    "rel": "stack"
+                }
+            ],
+            "logical_resource_id": "random_key_name",
+            "physical_resource_id": "mystack-random_key_name-pmjmy5pks735",
+            "required_by": [],
+            "resource_name": "random_key_name",
+            "resource_status": "CREATE_COMPLETE",
+            "resource_status_reason": "state changed",
+            "resource_type": "OS::Heat::RandomString",
+            "updated_time": "2015-06-25T14:59:53"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/services-list-response.json b/api-ref/source/v1/samples/services-list-response.json
new file mode 100644
index 0000000000..b49be73147
--- /dev/null
+++ b/api-ref/source/v1/samples/services-list-response.json
@@ -0,0 +1,30 @@
+{
+    "services": [
+        {
+            "status": "up",
+            "binary": "heat-engine",
+            "report_interval": 60,
+            "engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d",
+            "created_at": "2015-02-03T05:55:59.000000",
+            "hostname": "mrkanag",
+            "updated_at": "2015-02-03T05:57:59.000000",
+            "topic": "engine",
+            "host": "engine-1",
+            "deleted_at": null,
+            "id": "e1908f44-42f9-483f-b778-bc814072c33d"
+        },
+        {
+            "status": "down",
+            "binary": "heat-engine",
+            "report_interval": 60,
+            "engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306",
+            "created_at": "2015-02-03T06:03:14.000000",
+            "hostname": "mrkanag",
+            "updated_at": "2015-02-03T06:09:55.000000",
+            "topic": "engine",
+            "host": "engine",
+            "deleted_at": null,
+            "id": "582b5657-6db7-48ad-8483-0096350faa21"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/stack-abandon-response.json b/api-ref/source/v1/samples/stack-abandon-response.json
new file mode 100644
index 0000000000..57bd22da23
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-abandon-response.json
@@ -0,0 +1,69 @@
+{
+    "status": "COMPLETE",
+    "name": "g",
+    "dry_run": true,
+    "template": {
+        "outputs": {
+            "instance_ip": {
+                "value": {
+                    "str_replace": {
+                        "params": {
+                            "username": "ec2-user",
+                            "hostname": {
+                                "get_attr": [
+                                    "server",
+                                    "first_address"
+                                ]
+                            }
+                        },
+                        "template": "ssh username@hostname"
+                    }
+                }
+            }
+        },
+        "heat_template_version": "2013-05-23",
+        "resources": {
+            "server": {
+                "type": "OS::Nova::Server",
+                "properties": {
+                    "key_name": {
+                        "get_param": "key_name"
+                    },
+                    "image": {
+                        "get_param": "image"
+                    },
+                    "flavor": {
+                        "get_param": "flavor"
+                    }
+                }
+            }
+        },
+        "parameters": {
+            "key_name": {
+                "default": "heat_key",
+                "type": "string"
+            },
+            "image": {
+                "default": "fedora-amd64",
+                "type": "string"
+            },
+            "flavor": {
+                "default": "m1.small",
+                "type": "string"
+            }
+        }
+    },
+    "action": "CREATE",
+    "id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
+    "resources": {
+        "server": {
+            "status": "COMPLETE",
+            "name": "server",
+            "resource_data": {},
+            "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
+            "action": "CREATE",
+            "type": "OS::Nova::Server",
+            "metadata": {}
+        }
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-action-cancel-update-request.json b/api-ref/source/v1/samples/stack-action-cancel-update-request.json
new file mode 100644
index 0000000000..ad76bd690b
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-action-cancel-update-request.json
@@ -0,0 +1,3 @@
+{
+    "cancel_update": null
+}
diff --git a/api-ref/source/v1/samples/stack-action-check-request.json b/api-ref/source/v1/samples/stack-action-check-request.json
new file mode 100644
index 0000000000..019b28e776
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-action-check-request.json
@@ -0,0 +1,3 @@
+{
+    "check": null
+}
diff --git a/api-ref/source/v1/samples/stack-action-resume-request.json b/api-ref/source/v1/samples/stack-action-resume-request.json
new file mode 100644
index 0000000000..ff00d97a14
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-action-resume-request.json
@@ -0,0 +1,3 @@
+{
+    "resume": null
+}
diff --git a/api-ref/source/v1/samples/stack-action-suspend-request.json b/api-ref/source/v1/samples/stack-action-suspend-request.json
new file mode 100644
index 0000000000..8c2206a063
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-action-suspend-request.json
@@ -0,0 +1,3 @@
+{
+    "suspend": null
+}
diff --git a/api-ref/source/v1/samples/stack-adopt-request.json b/api-ref/source/v1/samples/stack-adopt-request.json
new file mode 100644
index 0000000000..242afb1611
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-adopt-request.json
@@ -0,0 +1,33 @@
+{
+    "adopt_stack_data": {
+        "action": "CREATE",
+        "id": "bxxxxx4-0xx2-4xx1-axx6-exxxxxxxc",
+        "name": "teststack",
+        "resources": {
+            "MyServer": {
+                "action": "CREATE",
+                "metadata": {},
+                "name": "MyServer",
+                "resource_data": {},
+                "resource_id": "cxxxx3-dxx3-4xx-bxx2-3xxxxxxxxa",
+                "status": "COMPLETE",
+                "type": "OS::Trove::Instance"
+            }
+        },
+        "status": "COMPLETE",
+        "template": {
+            "heat_template_version": "2013-05-23",
+            "resources": {
+                "MyServer": {
+                    "type": "OS::Trove::Instance",
+                    "properties": {
+                        "flavor": "m1.small",
+                        "size": 10
+                    }
+                }
+            }
+        }
+    },
+    "stack_name": "{stack_name}",
+    "timeout_mins": "{timeout_mins}"
+}
diff --git a/api-ref/source/v1/samples/stack-create-request.json b/api-ref/source/v1/samples/stack-create-request.json
new file mode 100644
index 0000000000..9b03d44bf9
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-create-request.json
@@ -0,0 +1,32 @@
+{
+    "files": {},
+    "disable_rollback": true,
+    "parameters": {
+        "flavor": "m1.heat"
+    },
+    "stack_name": "teststack",
+    "template": {
+        "heat_template_version": "2013-05-23",
+        "description": "Simple template to test heat commands",
+        "parameters": {
+            "flavor": {
+                "default": "m1.tiny",
+                "type": "string"
+            }
+        },
+        "resources": {
+            "hello_world": {
+                "type": "OS::Nova::Server",
+                "properties": {
+                    "key_name": "heat_key",
+                    "flavor": {
+                        "get_param": "flavor"
+                    },
+                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
+                    "user_data": "#!/bin/bash -xv\necho \"hello world\" &gt; /root/hello-world.txt\n"
+                }
+            }
+        }
+    },
+    "timeout_mins": 60
+}
diff --git a/api-ref/source/v1/samples/stack-create-response.json b/api-ref/source/v1/samples/stack-create-response.json
new file mode 100644
index 0000000000..81c91ce7fd
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-create-response.json
@@ -0,0 +1,11 @@
+{
+    "stack": {
+        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+        "links": [
+            {
+                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/teststack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+                "rel": "self"
+            }
+        ]
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-find-response.json b/api-ref/source/v1/samples/stack-find-response.json
new file mode 100644
index 0000000000..06b05c5c54
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-find-response.json
@@ -0,0 +1,27 @@
+{
+    "stack": {
+        "capabilities": [],
+        "creation_time": "2014-06-04T20:36:12Z",
+        "description": "sample stack",
+        "disable_rollback": true,
+        "id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
+        "links": [
+            {
+                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/5333af0c-cc26-47ee-ac3d-8784cefafbd7",
+                "rel": "self"
+            }
+        ],
+        "notification_topics": [],
+        "outputs": [],
+        "parameters": {
+            "OS::stack_id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
+            "OS::stack_name": "simple_stack"
+        },
+        "stack_name": "simple_stack",
+        "stack_status": "CREATE_COMPLETE",
+        "stack_status_reason": "Stack CREATE completed successfully",
+        "template_description": "sample stack",
+        "timeout_mins": null,
+        "updated_time": null
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-outputs-list-response.json b/api-ref/source/v1/samples/stack-outputs-list-response.json
new file mode 100644
index 0000000000..8cb61499f1
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-outputs-list-response.json
@@ -0,0 +1,10 @@
+{
+    "outputs": [
+        {
+            "output_key": "output name",
+            "output_value": "output value",
+            "description": "output description",
+            "output_error": null
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/stack-preview-response.json b/api-ref/source/v1/samples/stack-preview-response.json
new file mode 100644
index 0000000000..a36f8cf5d2
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-preview-response.json
@@ -0,0 +1,168 @@
+{
+    "stack": {
+        "capabilities": [],
+        "creation_time": "2015-01-31T15:12:36Z",
+        "description": "HOT template for Nova Server resource.\n",
+        "disable_rollback": true,
+        "id": "None",
+        "links": [
+            {
+                "href": "http://192.168.122.102:8004/v1/6e18cc2bdbeb48a5basad2dc499f6804/stacks/test_stack/None",
+                "rel": "self"
+            }
+        ],
+        "notification_topics": [],
+        "parameters": {
+            "OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804",
+            "OS::stack_id": "None",
+            "OS::stack_name": "teststack",
+            "admin_user": "cloud-user",
+            "flavor": "m1.small",
+            "image": "F20-cfg",
+            "key_name": "heat_key",
+            "server_name": "MyServer"
+        },
+        "parent": null,
+        "resources": [
+            {
+                "attributes": {},
+                "description": "",
+                "metadata": {},
+                "physical_resource_id": "",
+                "properties": {
+                    "description": "Ping and SSH",
+                    "name": "the_sg",
+                    "rules": [
+                        {
+                            "direction": "ingress",
+                            "ethertype": "IPv4",
+                            "port_range_max": null,
+                            "port_range_min": null,
+                            "protocol": "icmp",
+                            "remote_group_id": null,
+                            "remote_ip_prefix": null,
+                            "remote_mode": "remote_ip_prefix"
+                        },
+                        {
+                            "direction": "ingress",
+                            "ethertype": "IPv4",
+                            "port_range_max": 65535,
+                            "port_range_min": 1,
+                            "protocol": "tcp",
+                            "remote_group_id": null,
+                            "remote_ip_prefix": null,
+                            "remote_mode": "remote_ip_prefix"
+                        },
+                        {
+                            "direction": "ingress",
+                            "ethertype": "IPv4",
+                            "port_range_max": 65535,
+                            "port_range_min": 1,
+                            "protocol": "udp",
+                            "remote_group_id": null,
+                            "remote_ip_prefix": null,
+                            "remote_mode": "remote_ip_prefix"
+                        }
+                    ]
+                },
+                "required_by": [
+                    "server1"
+                ],
+                "resource_action": "INIT",
+                "resource_identity": {
+                    "path": "/resources/the_sg_res",
+                    "stack_id": "None",
+                    "stack_name": "teststack",
+                    "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
+                },
+                "resource_name": "the_sg_res",
+                "resource_status": "COMPLETE",
+                "resource_status_reason": "",
+                "resource_type": "OS::Neutron::SecurityGroup",
+                "stack_identity": {
+                    "path": "",
+                    "stack_id": "None",
+                    "stack_name": "teststack",
+                    "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
+                },
+                "stack_name": "teststack",
+                "updated_time": "2015-01-31T15:12:36Z"
+            },
+            {
+                "attributes": {
+                    "accessIPv4": "",
+                    "accessIPv6": "",
+                    "addresses": "",
+                    "console_urls": "",
+                    "first_address": "",
+                    "instance_name": "",
+                    "name": "MyServer",
+                    "networks": "",
+                    "show": ""
+                },
+                "description": "",
+                "metadata": {},
+                "physical_resource_id": "",
+                "properties": {
+                    "admin_pass": null,
+                    "admin_user": "cloud-user",
+                    "availability_zone": null,
+                    "block_device_mapping": null,
+                    "config_drive": null,
+                    "diskConfig": null,
+                    "flavor": "m1.small",
+                    "flavor_update_policy": "RESIZE",
+                    "image": "F20-cfg",
+                    "image_update_policy": "REPLACE",
+                    "key_name": "heat_key",
+                    "metadata": {
+                        "ha_stack": "None"
+                    },
+                    "name": "MyServer",
+                    "networks": [
+                        {
+                            "fixed_ip": null,
+                            "network": "private",
+                            "port": null,
+                            "uuid": null
+                        }
+                    ],
+                    "personality": {},
+                    "reservation_id": null,
+                    "scheduler_hints": null,
+                    "security_groups": [
+                        "None"
+                    ],
+                    "software_config_transport": "POLL_SERVER_CFN",
+                    "user_data": "",
+                    "user_data_format": "HEAT_CFNTOOLS"
+                },
+                "required_by": [],
+                "resource_action": "INIT",
+                "resource_identity": {
+                    "path": "/resources/hello_world",
+                    "stack_id": "None",
+                    "stack_name": "teststack",
+                    "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
+                },
+                "resource_name": "hello_world",
+                "resource_status": "COMPLETE",
+                "resource_status_reason": "",
+                "resource_type": "OS::Nova::Server",
+                "stack_identity": {
+                    "path": "",
+                    "stack_id": "None",
+                    "stack_name": "teststack",
+                    "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
+                },
+                "stack_name": "teststack",
+                "updated_time": "2015-01-31T15:12:36Z"
+            }
+        ],
+        "stack_name": "test_stack",
+        "stack_owner": "admin",
+        "template_description": "HOT template for Nova Server resource.\n",
+        "timeout_mins": null,
+        "updated_time": null
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-show-output-response.json b/api-ref/source/v1/samples/stack-show-output-response.json
new file mode 100644
index 0000000000..356eb60b6e
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-show-output-response.json
@@ -0,0 +1,8 @@
+{
+    "output": {
+        "output_key": "output_name",
+        "output_value": "output_value",
+        "description": "output description",
+        "output_error": null
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-show-response.json b/api-ref/source/v1/samples/stack-show-response.json
new file mode 100644
index 0000000000..c0b840c1ed
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-show-response.json
@@ -0,0 +1,32 @@
+{
+    "stack": {
+        "capabilities": [],
+        "creation_time": "2014-06-03T20:59:46Z",
+        "description": "sample stack",
+        "disable_rollback": true,
+        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+        "links": [
+            {
+                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+                "rel": "self"
+            }
+        ],
+        "notification_topics": [],
+        "outputs": [],
+        "parameters": {
+            "OS::project_id": "3ab5b02f-a01f-4f95-afa1-e254afc4a435",
+            "OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+            "OS::stack_name": "simple_stack"
+        },
+        "stack_name": "simple_stack",
+        "stack_owner": "simple_username",
+        "stack_status": "CREATE_COMPLETE",
+        "stack_status_reason": "Stack CREATE completed successfully",
+        "template_description": "sample stack",
+        "stack_user_project_id": "65728b74-cfe7-4f17-9c15-11d4f686e591",
+        "timeout_mins": "",
+        "updated_time": "",
+        "parent": "",
+        "tags": ""
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-show-snapshot-response.json b/api-ref/source/v1/samples/stack-show-snapshot-response.json
new file mode 100644
index 0000000000..6646b9fb27
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-show-snapshot-response.json
@@ -0,0 +1,47 @@
+{
+    "snapshot": {
+        "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1",
+        "name": "vol_snapshot",
+        "status": "COMPLETE",
+        "status_reason": "Stack SNAPSHOT completed successfully",
+        "creation_time": "2015-08-04T20:57:55Z",
+        "data": {
+            "status": "COMPLETE",
+            "name": "stack_vol1",
+            "stack_user_project_id": "fffa11067b1c48129ddfb78fba2bf09f",
+            "environment": {
+                "parameters": {},
+                "resource_registry": {
+                    "resources": {}
+                }
+            },
+            "template": {
+                "heat_template_version": "2013-05-23",
+                "resources": {
+                    "volume": {
+                        "type": "OS::Cinder::Volume",
+                        "properties": {
+                            "size": 1
+                        }
+                    }
+                }
+            },
+            "action": "SNAPSHOT",
+            "project_id": "ecdb08032cd042179692a1b148f6565e",
+            "id": "656452c2-e151-40da-8704-c844e69b485c",
+            "resources": {
+                "volume": {
+                    "status": "COMPLETE",
+                    "name": "volume",
+                    "resource_data": {
+                        "backup_id": "99108cf8-398f-461b-a043-bdceb7c9f572"
+                    },
+                    "resource_id": "3ab8cf79-807b-4c40-b743-0655f91e072f",
+                    "action": "SNAPSHOT",
+                    "type": "OS::Cinder::Volume",
+                    "metadata": {}
+                }
+            }
+        }
+    }
+}
diff --git a/api-ref/source/v1/samples/stack-snapshot-request.json b/api-ref/source/v1/samples/stack-snapshot-request.json
new file mode 100644
index 0000000000..f7d3a6210c
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-snapshot-request.json
@@ -0,0 +1,3 @@
+{
+    "name": "vol_snapshot"
+}
diff --git a/api-ref/source/v1/samples/stack-snapshot-response.json b/api-ref/source/v1/samples/stack-snapshot-response.json
new file mode 100644
index 0000000000..d3ecfcde1d
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-snapshot-response.json
@@ -0,0 +1,8 @@
+{
+    "id": "13c3a4b5-0585-440e-85a4-6f96b20e7a78",
+    "name": "vol_snapshot",
+    "status": "IN_PROGRESS",
+    "status_reason": null,
+    "data": null,
+    "creation_time": "2015-09-01T20:57:55Z"
+}
diff --git a/api-ref/source/v1/samples/stack-snapshots-list-response.json b/api-ref/source/v1/samples/stack-snapshots-list-response.json
new file mode 100644
index 0000000000..d25bdf114c
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-snapshots-list-response.json
@@ -0,0 +1,12 @@
+{
+    "snapshots": [
+        {
+            "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1",
+            "name": "vol_snapshot",
+            "status": "IN_PROGRESS",
+            "status_reason": null,
+            "creation_time": "2015-08-04T20:57:55Z",
+            "data": null
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/stack-update-preview-response.json b/api-ref/source/v1/samples/stack-update-preview-response.json
new file mode 100644
index 0000000000..9a511a1788
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-update-preview-response.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}"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/stack-update-request.json b/api-ref/source/v1/samples/stack-update-request.json
new file mode 100644
index 0000000000..407a3c03c2
--- /dev/null
+++ b/api-ref/source/v1/samples/stack-update-request.json
@@ -0,0 +1,28 @@
+{
+    "template": {
+        "heat_template_version": "2013-05-23",
+        "description": "Create a simple stack",
+        "parameters": {
+            "flavor": {
+                "default": "m1.tiny",
+                "type": "string"
+            }
+        },
+        "resources": {
+            "hello_world": {
+                "type": "OS::Nova::Server",
+                "properties": {
+                    "key_name": "heat_key",
+                    "flavor": {
+                        "get_param": "flavor"
+                    },
+                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
+                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
+                }
+            }
+        }
+    },
+    "parameters": {
+        "flavor": "m1.small"
+    }
+}
diff --git a/api-ref/source/v1/samples/stacks-list-response.json b/api-ref/source/v1/samples/stacks-list-response.json
new file mode 100644
index 0000000000..b758c840c6
--- /dev/null
+++ b/api-ref/source/v1/samples/stacks-list-response.json
@@ -0,0 +1,20 @@
+{
+    "stacks": [
+        {
+            "creation_time": "2014-06-03T20:59:46Z",
+            "description": "sample stack",
+            "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+            "links": [
+                {
+                    "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
+                    "rel": "self"
+                }
+            ],
+            "stack_name": "simple_stack",
+            "stack_status": "CREATE_COMPLETE",
+            "stack_status_reason": "Stack CREATE completed successfully",
+            "updated_time": "",
+            "tags": ""
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/template-show-response.json b/api-ref/source/v1/samples/template-show-response.json
new file mode 100644
index 0000000000..06cdc4c33b
--- /dev/null
+++ b/api-ref/source/v1/samples/template-show-response.json
@@ -0,0 +1,28 @@
+{
+    "description": "Hello world HOT template that just defines a single server. Contains just base features to verify base HOT support.\n",
+    "heat_template_version": "2013-05-23",
+    "outputs": {
+        "foo": {
+            "description": "Show foo parameter value",
+            "value": {
+                "get_param": "foo"
+            }
+        }
+    },
+    "parameters": {
+        "foo": {
+            "default": "secret",
+            "description": "Name of an existing key pair to use for the server",
+            "hidden": true,
+            "type": "string"
+        }
+    },
+    "resources": {
+        "random_key_name": {
+            "properties": {
+                "length": 8
+            },
+            "type": "OS::Heat::RandomString"
+        }
+    }
+}
diff --git a/api-ref/source/v1/samples/template-validate-request.json b/api-ref/source/v1/samples/template-validate-request.json
new file mode 100644
index 0000000000..7ba5f97869
--- /dev/null
+++ b/api-ref/source/v1/samples/template-validate-request.json
@@ -0,0 +1,3 @@
+{
+    "template_url": "/PATH_TO_HEAT_TEMPLATES/WordPress_Single_Instance.template"
+}
diff --git a/api-ref/source/v1/samples/template-validate-response.json b/api-ref/source/v1/samples/template-validate-response.json
new file mode 100644
index 0000000000..cbdf7c26f1
--- /dev/null
+++ b/api-ref/source/v1/samples/template-validate-response.json
@@ -0,0 +1,41 @@
+{
+    "Description": "A template that provides a single server instance.",
+    "Parameters": {
+        "server-size": {
+            "default": "1GB Standard Instance",
+            "description": "Server size",
+            "type": "String",
+            "constraints": [
+                {
+                    "allowed_values": [
+                        "512MB Standard Instance",
+                        "1GB Standard Instance",
+                        "4GB Standard Instance",
+                        "8GB Standard Instance"
+                    ],
+                    "description": "Must be a valid server size."
+                }
+            ]
+        },
+        "key_name": {
+            "description": "Keypair name for SSH access to the server",
+            "required": true,
+            "type": "String"
+        },
+        "server_name": {
+            "default": "My server",
+            "description": "My server",
+            "type": "String"
+        }
+    },
+    "ParameterGroups": [
+        {
+            "label": "Parameter groups",
+            "description": "My parameter groups",
+            "parameters": [
+                "param_name-1",
+                "param_name-2"
+            ]
+        }
+    ]
+}
diff --git a/api-ref/source/v1/samples/template-versions-response.json b/api-ref/source/v1/samples/template-versions-response.json
new file mode 100644
index 0000000000..f82a8c2a17
--- /dev/null
+++ b/api-ref/source/v1/samples/template-versions-response.json
@@ -0,0 +1,32 @@
+{
+    "template_versions": [
+        {
+            "version": "heat_template_version.2014-10-16",
+            "type": "hot"
+        },
+        {
+            "version": "heat_template_version.2015-04-30",
+            "type": "hot"
+        },
+        {
+            "version": "HeatTemplateFormatVersion.2012-12-12",
+            "type": "cfn"
+        },
+        {
+            "version": "heat_template_version.2015-10-15",
+            "type": "hot"
+        },
+        {
+            "version": "AWSTemplateFormatVersion.2010-09-09",
+            "type": "cfn"
+        },
+        {
+            "version": "heat_template_version.2013-05-23",
+            "type": "hot"
+        },
+        {
+            "version": "heat_template_version.2016-04-08",
+            "type": "hot"
+        }
+    ]
+}
diff --git a/api-ref/source/v1/service-status.inc b/api-ref/source/v1/service-status.inc
new file mode 100644
index 0000000000..e6940bb2bf
--- /dev/null
+++ b/api-ref/source/v1/service-status.inc
@@ -0,0 +1,67 @@
+.. -*- rst -*-
+
+==============
+Manage service
+==============
+
+
+
+
+Show orchestration engine status
+================================
+
+.. rest_method::  GET /v1/{tenant_id}/services
+
+Enables administrative users to view details for all orchestration engines.
+
+Orchestration engine details include ``engine_id``, topic name,
+last updated time, health status, and host name.
+
+Troubleshooting
+
+- A ``503`` error code indicates that the heat engines are not
+  operational. Run the heat-manage service list command or contact
+  your cloud provider to determine why the heat engines are not
+  operational.
+
+
+Normal response codes: 200
+Error response codes:403,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - binary: binary
+   - report_interval: report_interval
+   - created_at: created_at
+   - hostname: hostname
+   - updated_at: updated_at
+   - topic: topic
+   - services: services
+   - deleted_at: deleted_at
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/services-list-response.json
+   :language: javascript
+
+
+
+
+
diff --git a/api-ref/source/v1/software-config.inc b/api-ref/source/v1/software-config.inc
new file mode 100644
index 0000000000..e79cc5d3c1
--- /dev/null
+++ b/api-ref/source/v1/software-config.inc
@@ -0,0 +1,416 @@
+.. -*- rst -*-
+
+======================
+Software configuration
+======================
+
+
+
+
+List deployments
+================
+
+.. rest_method::  GET /v1/{tenant_id}/software_deployments
+
+Lists all available software deployments.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - server_id: server_id
+   - config_id: config_id
+   - output_values: output_values
+   - creation_time: creation_time
+   - updated_at: updated_at
+   - input_values: input_values
+   - action: action
+   - status_reason: status_reason
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployments-list-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Create deployment
+=================
+
+.. rest_method::  POST /v1/{tenant_id}/software_deployments
+
+Creates a software deployment.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - server_id: server_id
+   - config_id: config_id
+   - stack_user_project_id: stack_user_project_id
+   - action: action
+   - status_reason: status_reason
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/deployment-create-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - server_id: server_id
+   - config_id: config_id
+   - output_values: output_values
+   - creation_time: creation_time
+   - updated_at: updated_at
+   - input_values: input_values
+   - action: action
+   - status_reason: status_reason
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployment-create-response.json
+   :language: javascript
+
+
+
+
+Show server configuration metadata
+==================================
+
+.. rest_method::  GET /v1/{tenant_id}/software_deployments/metadata/{server_id}
+
+Shows the deployment configuration metadata for a server.
+
+Use the ``group`` property to specify the configuration hook to
+which the pass the metadata item.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - server_id: server_id
+   - tenant_id: tenant_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployment-metadata-response.json
+   :language: javascript
+
+
+
+
+Create configuration
+====================
+
+.. rest_method::  POST /v1/{tenant_id}/software_configs
+
+Creates a software configuration.
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - inputs: inputs
+   - group: group
+   - name: name
+   - outputs: outputs
+   - config: config
+   - options: options
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/config-create-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - inputs: inputs
+   - group: group
+   - name: name
+   - outputs: outputs
+   - creation_time: creation_time
+   - config: config
+   - options: options
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/config-create-response.json
+   :language: javascript
+
+
+
+
+
+
+
+Show deployment details
+=======================
+
+.. rest_method::  GET /v1/{tenant_id}/software_deployments/{deployment_id}
+
+Shows details for a software deployment.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - deployment_id: deployment_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - server_id: server_id
+   - config_id: config_id
+   - output_values: output_values
+   - creation_time: creation_time
+   - updated_at: updated_at
+   - input_values: input_values
+   - action: action
+   - status_reason: status_reason
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployment-show-response.json
+   :language: javascript
+
+
+
+
+Update deployment
+=================
+
+.. rest_method::  PUT /v1/{tenant_id}/software_deployments/{deployment_id}
+
+Updates a software deployment.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - action: action
+   - output_values: output_values
+   - config_id: config_id
+   - status: status
+   - status_reason: status_reason
+   - tenant_id: tenant_id
+   - deployment_id: deployment_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/deployment-update-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - server_id: server_id
+   - config_id: config_id
+   - output_values: output_values
+   - creation_time: creation_time
+   - updated_at: updated_at
+   - input_values: input_values
+   - action: action
+   - status_reason: status_reason
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deployment-update-response.json
+   :language: javascript
+
+
+
+
+Delete deployment
+=================
+
+.. rest_method::  DELETE /v1/{tenant_id}/software_deployments/{deployment_id}
+
+Deletes a software deployment.
+
+Error response codes:204,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - deployment_id: deployment_id
+
+
+
+
+
+
+Show configuration details
+==========================
+
+.. rest_method::  GET /v1/{tenant_id}/software_configs/{config_id}
+
+Shows details for a software configuration.
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - config_id: config_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - inputs: inputs
+   - group: group
+   - name: name
+   - outputs: outputs
+   - creation_time: creation_time
+   - config: config
+   - options: options
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/config-show-response.json
+   :language: javascript
+
+
+
+
+
+
+
+Delete config
+=============
+
+.. rest_method::  DELETE /v1/{tenant_id}/software_configs/{config_id}
+
+Deletes a software configuration.
+
+Error response codes:204,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - config_id: config_id
+
+
+
+
+
diff --git a/api-ref/source/v1/stack-actions.inc b/api-ref/source/v1/stack-actions.inc
new file mode 100644
index 0000000000..e1d49ac761
--- /dev/null
+++ b/api-ref/source/v1/stack-actions.inc
@@ -0,0 +1,173 @@
+.. -*- rst -*-
+
+=============
+Stack actions
+=============
+
+Performs non-lifecycle operations on the stack. Specify the action
+in the request body.
+
+
+Suspend stack
+=============
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions
+
+Suspends a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - suspend: suspend
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-action-suspend-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: 
+   :language: javascript
+
+
+
+
+Resume stack
+============
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions
+
+Resumes a suspended stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resume: resume
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-action-resume-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: 
+   :language: javascript
+
+
+
+
+Cancel stack update
+===================
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions
+
+Cancels a currently running update of a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - cancel_update: cancel_update
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-action-cancel-update-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: 
+   :language: javascript
+
+
+
+
+Check stack resources
+=====================
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions
+
+Checks whether the resources are in expected states for a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - check: check
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-action-check-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: 
+   :language: javascript
+
+
+
diff --git a/api-ref/source/v1/stack-events.inc b/api-ref/source/v1/stack-events.inc
new file mode 100644
index 0000000000..f51f31a0b2
--- /dev/null
+++ b/api-ref/source/v1/stack-events.inc
@@ -0,0 +1,155 @@
+.. -*- rst -*-
+
+============
+Stack events
+============
+
+
+
+
+Show event details
+==================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id}
+
+Shows details for an event.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - event_id: event_id
+   - stack_id: stack_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/event-show-response.json
+   :language: javascript
+
+
+
+
+Find stack events
+=================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/events
+
+Finds the canonical URL for the event list of a stack.
+
+Error response codes:302,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+
+
+
+
+
+
+List stack events
+=================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events
+
+Lists events for a stack.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - resource_action: resource_action
+   - resource_status: resource_status
+   - resource_name: resource_name
+   - resource_type: resource_type
+   - limit: limit
+   - marker: marker
+   - sort_keys: sort_keys
+   - sort_dir: sort_dir
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/events-list-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+List resource events
+====================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events
+
+Lists events for a stack resource.
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - resource_action: resource_action
+   - resource_status: resource_status
+   - resource_type: resource_type
+   - limit: limit
+   - marker: marker
+   - sort_keys: sort_keys
+   - sort_dir: sort_dir
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/events-list-response.json
+   :language: javascript
+
+
+
+
+
+
diff --git a/api-ref/source/v1/stack-resources.inc b/api-ref/source/v1/stack-resources.inc
new file mode 100644
index 0000000000..23f6f46f8d
--- /dev/null
+++ b/api-ref/source/v1/stack-resources.inc
@@ -0,0 +1,191 @@
+.. -*- rst -*-
+
+===============
+Stack resources
+===============
+
+
+
+
+Show resource metadata
+======================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata
+
+Shows metadata for a resource.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-metadata-response.json
+   :language: javascript
+
+
+
+
+Show resource data
+==================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}
+
+Shows data for a resource.
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - resource: resource
+   - description: description
+   - logical_resource_id: logical_resource_id
+   - creation_time: creation_time
+   - resource_status: resource_status
+   - updated_time: updated_time
+   - required_by: required_by
+   - resource_status_reason: resource_status_reason
+   - physical_resource_id: physical_resource_id
+   - resource_type: resource_type
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-show-response.json
+   :language: javascript
+
+
+
+
+
+
+
+List resources
+==============
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
+
+Lists resources in a stack.
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - nested_depth: nested_depth
+   - with_detail: with_detail
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - description: description
+   - logical_resource_id: logical_resource_id
+   - creation_time: creation_time
+   - resource_status: resource_status
+   - updated_time: updated_time
+   - required_by: required_by
+   - resources: resources
+   - resource_status_reason: resource_status_reason
+   - physical_resource_id: physical_resource_id
+   - resource_type: resource_type
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resources-list-response.json
+   :language: javascript
+
+
+
+
+
+
+
+Send a signal to a resource
+===========================
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/signal
+
+Sends a signal to a resource.
+
+The contents of the request body depends on the resource to which
+you send a signal.
+
+Some resources cannot receive signals. If you send them a signal,
+they return a 400 error code.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_name: resource_name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: 
+   :language: javascript
+
+
+
diff --git a/api-ref/source/v1/stack-templates.inc b/api-ref/source/v1/stack-templates.inc
new file mode 100644
index 0000000000..aa5e229f65
--- /dev/null
+++ b/api-ref/source/v1/stack-templates.inc
@@ -0,0 +1,300 @@
+.. -*- rst -*-
+
+=========
+Templates
+=========
+
+
+
+
+List resource types
+===================
+
+.. rest_method::  GET /v1/{tenant_id}/resource_types
+
+Lists all supported template resource types.
+
+
+Normal response codes: 200
+Error response codes:401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - name: name
+   - version: version
+   - support_status: support_status
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - template_versions: template_versions
+   - type: type
+   - version: version
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-types-list-response.json
+   :language: javascript
+
+
+
+
+
+
+List template versions
+======================
+
+.. rest_method::  GET /v1/{tenant_id}/template_versions
+
+Lists all available template versions.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/template-versions-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Validate template
+=================
+
+.. rest_method::  POST /v1/{tenant_id}/validate
+
+Validates a template.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - environment: environment
+   - template_url: template_url
+   - template: template
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/template-validate-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - ParameterGroups: ParameterGroups
+   - Description: Description
+   - Parameters: Parameters
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/template-validate-response.json
+   :language: javascript
+
+
+
+
+Show resource template
+======================
+
+.. rest_method::  GET /v1/{tenant_id}/resource_types/{type_name}/template
+
+Shows the template representation for a resource type.
+
+The returned template contains a single resource type. Each
+resource property is mapped to a template parameter and each
+resource attribute is mapped to a template output.
+
+You can use these templates as a starting place for creating
+customized, template-based resources or as examples of using the
+particular resource in another template.
+
+Use the ``template_type`` query parameter to specify the resource
+template type. Default type is ``cfn``. The ``hot`` template type
+is supported. For example:
+
+::
+
+   /v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn
+
+
+Normal response codes: 200
+Error response codes:404,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - type_name: type_name
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - Outputs: Outputs
+   - HeatTemplateFormatVersion: HeatTemplateFormatVersion
+   - Resources: Resources
+   - Parameters: Parameters
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-type-template-response.json
+   :language: javascript
+
+
+
+
+
+
+
+Get stack template
+==================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template
+
+Gets a template for a stack.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - outputs: outputs
+   - heat_template_version: heat_template_version
+   - description: description
+   - parameters: parameters
+   - resources: resources
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/template-show-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Show resource schema
+====================
+
+.. rest_method::  GET /v1/{tenant_id}/resource_types/{type_name}
+
+Shows the interface schema for a resource type.
+
+A schema describes the properties that can be set on the resource,
+their types, constraints, descriptions, and default values.
+Additionally, the response shows the resource attributes and their
+descriptions.
+
+
+Normal response codes: 200
+Error response codes:401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - type_name: type_name
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - description: description
+   - required: required
+   - update_allowed: update_allowed
+   - support_status: support_status
+   - attributes: attributes
+   - type: type
+   - properties: properties
+   - resource_type: resource_type
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/resource-schema-response.json
+   :language: javascript
+
+
+
+
+
diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc
new file mode 100644
index 0000000000..7594698de9
--- /dev/null
+++ b/api-ref/source/v1/stacks.inc
@@ -0,0 +1,818 @@
+.. -*- rst -*-
+
+======
+Stacks
+======
+
+
+
+
+Abandon stack
+=============
+
+.. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon
+
+Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources.
+
+This method can be disabled from the server side. If it is
+disabled, this call throws an exception.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-abandon-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Show snapshot
+=============
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
+
+Shows details for a snapshot.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - snapshot_id: snapshot_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - name: name
+   - status_reason: status_reason
+   - creation_time: creation_time
+   - snapshot: snapshot
+   - template: template
+   - project_id: project_id
+   - data: data
+   - id: id
+   - resources: resources
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-show-snapshot-response.json
+   :language: javascript
+
+
+
+
+Delete snapshot
+===============
+
+.. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}
+
+Deletes a stack snapshot.
+
+Error response codes:204,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - snapshot_id: snapshot_id
+
+
+
+
+
+
+Preview stack
+=============
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/preview
+
+Previews a stack.
+
+
+Normal response codes: 200
+Error response codes:500,409,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - files: files
+   - stack_name: stack_name
+   - template_url: template_url
+   - template: template
+   - parameters: parameters
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-create-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - parent: parent
+   - disable_rollback: disable_rollback
+   - description: description
+   - links: links
+   - stack_name: stack_name
+   - timeout_mins: timeout_mins
+   - creation_time: creation_time
+   - capabilities: capabilities
+   - notification_topics: notification_topics
+   - updated_time: updated_time
+   - stack_owner: stack_owner
+   - stack: stack
+   - parameters: parameters
+   - id: id
+   - resources: resources
+   - template_description: template_description
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-preview-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Restore snapshot
+================
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}/restore
+
+Restores a stack snapshot.
+
+You can restore only active stacks from a snapshot. You must
+recreate deleted stacks.
+
+Error response codes:202,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - snapshot_id: snapshot_id
+
+
+
+
+
+
+List outputs
+============
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs
+
+Lists outputs for a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - output_value: output_value
+   - output_error: output_error
+   - description: description
+   - output_key: output_key
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-outputs-list-response.json
+   :language: javascript
+
+
+
+
+Preview stack update
+====================
+
+.. rest_method::  PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview
+
+Previews an update for a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - files: files
+   - parameters: parameters
+   - tags: tags
+   - environment: environment
+   - template_url: template_url
+   - template: template
+   - timeout_mins: timeout_mins
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-update-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-update-preview-response.json
+   :language: javascript
+
+
+
+
+Find stack resources
+====================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/resources
+
+Finds the canonical URL for a resource list of a stack.
+
+The canonical URL is returned for only non-deleted stacks. To fetch
+the resource list for deleted stacks, use the following endpoint:
+
+::
+
+   /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
+
+Error response codes:302,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+
+
+
+
+
+
+Show stack details
+==================
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
+
+Shows details for a stack.
+
+
+Normal response codes: 200
+Error response codes:404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - parent: parent
+   - updated_time: updated_time
+   - description: description
+   - links: links
+   - stack_status_reason: stack_status_reason
+   - stack_name: stack_name
+   - outputs: outputs
+   - tags: tags
+   - creation_time: creation_time
+   - capabilities: capabilities
+   - notification_topics: notification_topics
+   - timeout_mins: timeout_mins
+   - stack_owner: stack_owner
+   - stack_status: stack_status
+   - stack: stack
+   - parameters: parameters
+   - id: id
+   - stack_user_project_id: stack_user_project_id
+   - template_description: template_description
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-show-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+Update stack
+============
+
+.. rest_method::  PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
+
+Updates a stack.
+
+Error response codes:404,202,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - files: files
+   - disable_rollback: disable_rollback
+   - parameters: parameters
+   - tags: tags
+   - environment: environment
+   - template_url: template_url
+   - template: template
+   - timeout_mins: timeout_mins
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-update-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+Delete stack
+============
+
+.. rest_method::  DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
+
+Deletes a stack and its snapshots.
+
+Error response codes:500,404,204,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+
+
+
+
+
+
+
+
+Show output
+===========
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key}
+
+Shows details for a stack output.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+   - output_key: output_key
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - output_value: output_value
+   - output_error: output_error
+   - description: description
+   - output_key: output_key
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-show-output-response.json
+   :language: javascript
+
+
+
+
+List stack data
+===============
+
+.. rest_method::  GET /v1/{tenant_id}/stacks
+
+Lists active stacks.
+
+
+Normal response codes: 200
+Error response codes:500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - id: id
+   - status: status
+   - name: name
+   - action: action
+   - tenant: tenant
+   - username: username
+   - owner_id: owner_id
+   - limit: limit
+   - marker: marker
+   - show_deleted: show_deleted
+   - show_nested: show_nested
+   - sort_keys: sort_keys
+   - tags: tags
+   - tags_any: tags_any
+   - not_tags: not_tags
+   - not_tags_any: not_tags_any
+   - sort_dir: sort_dir
+   - global_tenant: global_tenant
+   - with_count: with_count
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - description: description
+   - links: links
+   - stack_status_reason: stack_status_reason
+   - stack_name: stack_name
+   - tags: tags
+   - creation_time: creation_time
+   - updated_time: updated_time
+   - stack_status: stack_status
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stacks-list-response.json
+   :language: javascript
+
+
+
+
+
+
+
+Create stack
+============
+
+.. rest_method::  POST /v1/{tenant_id}/stacks
+
+Creates a stack.
+
+Error response codes:201,500,409,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - files: files
+   - disable_rollback: disable_rollback
+   - parameters: parameters
+   - tags: tags
+   - stack_name: stack_name
+   - environment: environment
+   - template_url: template_url
+   - template: template
+   - timeout_mins: timeout_mins
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-create-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id
+   - links: links
+   - stack: stack
+
+
+
+
+
+
+
+
+
+Adopt stack
+===========
+
+.. rest_method::  POST /v1/{tenant_id}/stacks
+
+Creates a stack from existing resources.
+
+Error response codes:201,500,409,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - files: files
+   - disable_rollback: disable_rollback
+   - parameters: parameters
+   - stack_name: stack_name
+   - adopt_stack_data: adopt_stack_data
+   - environment: environment
+   - timeout_mins: timeout_mins
+   - tenant_id: tenant_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-adopt-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id
+   - links: links
+   - stack: stack
+
+
+
+
+
+
+
+
+
+Find stack
+==========
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}
+
+Finds the canonical URL for a stack.
+
+Also works with verbs other than GET , so that you can perform PUT
+and DELETE operations on a current stack. Set your client to follow
+redirects. When redirecting, the request method should not change
+as defined in RFC2626. However, in many clients the default
+behavior is to change the method to GET when you receive a ``302``
+response code because this behavior is ubiquitous in web browsers.
+
+Error response codes:302,404,500,401,400,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+
+
+
+
+
+
+
+
+
+
+Snapshot stack
+==============
+
+.. rest_method::  POST /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
+
+Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: name
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/stack-snapshot-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - name: name
+   - status_reason: status_reason
+   - creation_time: creation_time
+   - data: data
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-snapshot-response.json
+   :language: javascript
+
+
+
+
+List snapshots
+==============
+
+.. rest_method::  GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots
+
+Lists snapshots for a stack.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - stack_name: stack_name
+   - tenant_id: tenant_id
+   - stack_id: stack_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status
+   - name: name
+   - status_reason: status_reason
+   - creation_time: creation_time
+   - snapshots: snapshots
+   - data: data
+   - id: id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-snapshots-list-response.json
+   :language: javascript
+
+
+
diff --git a/tox.ini b/tox.ini
index 5ccef4a9fd..4e01b56e33 100644
--- a/tox.ini
+++ b/tox.ini
@@ -54,6 +54,24 @@ deps = -r{toxinidir}/requirements.txt
        sphinxcontrib-httpdomain
 commands = python setup.py build_sphinx
 
+[testenv:api-ref]
+# This environment is called from CI scripts to test and publish
+# the API Ref to developer.openstack.org.
+#
+# NOTE(sdague): this target does not use constraints because
+# upstream infra does not yet support it. Once that's fixed, we can
+# drop the install_command.
+#
+# we do not used -W here because we are doing some slightly tricky
+# things to build a single page document, and as such, we are ok
+# ignoring the duplicate stanzas warning.
+whitelist_externals = bash
+                      rm
+install_command = pip install -U --force-reinstall {opts} {packages}
+commands =
+  rm -rf api-ref/build
+  sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+
 [testenv:genconfig]
 commands =
     oslo-config-generator --config-file=config-generator.conf