<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
        <!-- Some useful entities borrowed from HTML -->
        <!ENTITY ndash  "&#x2013;">
        <!ENTITY mdash  "&#x2014;">
        <!ENTITY hellip "&#x2026;">

        <!-- Useful for describing APIs -->
        <!ENTITY GET    '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
        <!ENTITY PUT    '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
        <!ENTITY POST   '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
        <!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
        
        <!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
        <!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
        <!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
        <!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
        <!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">
        
        <!-- changing product name; define entity for product name rather than maintaining in text -->
        <!ENTITY Checkmate "Orchestration">
        <!ENTITY Deployment "Orchestration">
        <!ENTITY DeploymentG "orchestration">

]>
<book xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:m="http://www.w3.org/1998/Math/MathML"
    xmlns:html="http://www.w3.org/1999/xhtml" xml:id="orchestration-api-v1-reference"
    version="5.0">
    <title>OpenStack Orchestration API v1 Reference</title>

    <info>
        <author>
            <personname>
                <firstname/>
                <surname/>
            </personname>
            <affiliation>
                <orgname>OpenStack LLC</orgname>
            </affiliation>
        </author>
        <copyright>
            <year>2012</year>
            <year>2013</year>
            <holder>OpenStack LLC</holder>
        </copyright>
        <releaseinfo>API v1</releaseinfo>
        <productname>OpenStack Orchestration</productname>
        <pubdate>2013-10-03</pubdate>
        <legalnotice role="apache2">
            <annotation>
                <remark>Copyright details are filled in by the template.</remark>
            </annotation>
        </legalnotice>
        <abstract>
            <para>This document is intended for software developers
                interested in developing applications using the
                OpenStack Orchestration Application Programming
                Interface (<abbrev>API</abbrev>). </para>
        </abstract>
        
        
        
        <revhistory>
            <revision>
                <date>2013-10-03</date>
                <revdescription>
                    <itemizedlist spacing="compact">
                        <listitem>
                            <para>Initial review.</para>
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </info>
    
   
    
    <chapter xml:id="overview">
        <title>Overview</title>
        <para> OpenStack &Deployment; is a service to deploy and
            manage multiple composite cloud applications on OpenStack
            clouds. Interactions with OpenStack &Deployment; occur
            programmatically via the OpenStack &Deployment; API as
            described in this document.</para>
        <remark security="writeronly">Reviewer: Can you provide me
            with a high-level Orchestration architecture diagram that
            I can add to this section?</remark>
        <para>We welcome feedback, comments, and bug reports at <link
            xlink:href="https://bugs.launchpad.net/heat"
            >https://bugs.launchpad.net/heat</link>.</para>
        <section xml:id="Intended_Audience-d1e122">
            <title>Intended Audience</title>
            <para> This Reference is intended to assist support teams,
                DevOps Engineers, and software developers who want to
                manage cloud applications with non-trivial
                architectures that leverage multiple OpenStack
                services.</para>
            <para>To use the information provided here, you should
                first have a general understanding of the &Deployment;
                service. You should also be familiar with: </para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>Other OpenStack services applicable to your
                        cloud application architecture (Nova, Cinder,
                        Neutron, and so forth)</para>
                </listitem>
                <listitem>
                    <para>ReSTful web services</para>
                </listitem>
                <listitem>
                    <para>JSON and/or YAML data serialization
                        formats</para>
                </listitem>
            </itemizedlist>
        </section>
        <?hard-pagebreak?>
        <section xml:id="Document_Change_History-d1e166">
            <title>Document Change History</title>
            <para>This version of the Reference replaces and obsoletes
                all previous versions. The most recent changes are
                described in the table below:</para>
        <?rax revhistory?>
        </section>
        <section xml:id="Additional_Resources-d1e532">
            <title>Additional Resources</title>
            <para>You can find information for developing templates in
                the <citetitle>Heat Orchestration Template (HOT)
                    Specification</citetitle> at <link
                        xlink:href="http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec"
                        >http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec</link>. </para>
            <para>You can find example templates at <link
                    xlink:href="https://github.com/heat-ci/heat-prod-templates/tree/master/example"
                    >https://github.com/heat-ci/heat-prod-templates/tree/master/example</link>. </para>
            <para>For information about OpenStack services, refer to
                    <link xlink:href="http://www.rackspace.com/cloud/"
                    >http://docs.openstack.org</link>.</para>
        </section>
    </chapter>
    <chapter xml:id="Concepts-d1e565">
        <title>Concepts</title>
        <?dbhtml stop-chunking?>
        <para> To use &Deployment; effectively, you should understand
            several key concepts: </para>
        <section xml:id="Stack-d1e573">
            <title>Stack</title>
            <para>A stack is a group of resources (servers, load
                balancers, databases, and so forth) combined to
                fulfill a useful purpose. A stack is a set of
                resources that can be deployed. A stack contains a
                template and generates resources to run the
                application framework or component specified.</para>
        </section>
        <section xml:id="Resource-d1e607">
            <title>Resource</title>
            <para>A resource is a template artifact that represents
                some component of your desired architecture (a Nova
                server, a group of scaled servers, a Cinder volume,
                some configuration management system, and so
                forth).</para>
        </section>
        <section xml:id="Blueprint-d1e588">
            <title>Template</title>
            <para>An &Deployment; template is a portable file, written
                in a user-readable language, that describes how a set
                of resources should be assembled and what software
                should be installed in order to produce a working
                deployment. The template specifies what resources
                should be used, what attributes can be set, and other
                parameters that are critical to the successful,
                repeatable automation of a specific application
                deployment.</para>
        </section>
    </chapter>
    <chapter xml:id="General_API_Information-d1e843">
        <title>General API Information</title>
        <para> The &Deployment; API is implemented using a ReSTful web
            service interface. Like other OpenStack services, the
            &Deployment; Service shares a common token-based
            authentication system that allows seamless access between
            products and services. </para>
        <section xml:id="Authentication-d1e647">
            <title>Authentication</title>
            <para> The &Deployment; Service supports standard Keystone
                authentication. For more information, refer to the
                    <citetitle>OpenStack Identity Service API v2.0
                    Reference</citetitle>. Please contact your
                provider for additional details on how to authenticate
                against this API.</para>
        </section>
        <section xml:id="Contract_Version-d1e825">
            <title>Contract Version</title>
            <para> The contract version denotes the data model and
                behavior that the API supports. The current contract
                version is v1. The requested contract version is
                included in all request URLs. Different contract
                versions of the API may be available at any given time
                and are not guaranteed to be compatible with one
                another. </para>
            <example>
                <title>Example Request URL (contract version in
                        <emphasis role="strong"
                    >bold</emphasis>)</title>
                <programlisting>https://openstack.example.com/<emphasis role="strong">v1</emphasis>/1234</programlisting>
            </example>
            <note>
                <para>This document pertains to contract version
                    1.</para>
            </note>
        </section>
        <?hard-pagebreak?>
        <section xml:id="Request_Response_Types-d1e903">
            <title>Request/Response Types</title>
            <para> The &Deployment; API supports both the JSON and
                YAML data serialization formats. The request format is
                specified using the <code>Content-Type</code> header
                and is <emphasis>required</emphasis> for calls that
                have a request body. The response format can be
                specified in requests either by using the
                    <code>Accept</code> header or by adding a
                    <code>.yaml</code> or <code>.json</code> extension
                to the request URI. Note that it is possible for a
                response to be serialized using a format different
                from the request. If no response format is specified,
                JSON is the default. If conflicting formats are
                specified using both an <code>Accept</code> header and
                a query extension, the query extension takes
                precedence.</para>
            <table rules="all">
                <caption>Response Formats</caption>
                <?dbfo keep-together="always"?>
                <thead>
                    <tr align="center">
                        <td>Format</td>
                        <td>Accept Header</td>
                        <td>Query Extension</td>
                        <td>Default</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>JSON</td>
                        <td>application/json</td>
                        <td>.json</td>
                        <td>Yes</td>
                    </tr>
                    <tr>
                        <td>YAML</td>
                        <td>application/yaml</td>
                        <td>.yaml</td>
                        <td>No</td>
                    </tr>
                </tbody>
            </table>
            <remark security="writeronly">Reviewer: need new examples
                below: one for "Request with Headers: JSON" and one
                for "Request with Headers: YAML".</remark>
            <para security="writeronly">In the request example below,
                notice that <parameter>Content-Type</parameter> is set
                to <parameter>application/json</parameter>, but
                    <parameter>application/yaml</parameter> is
                requested via the <parameter>Accept</parameter>
                header:</para>
            <para security="writeronly"
                ><?rax-fo keep-with-next?>Therefore a YAML response
                format is returned:</para>
        </section>
        <section xml:id="datetimeformat">
            <title>Date/Time Format</title>
            <para> The &Deployment; Service uses an ISO-8601 compliant
                date format for the display and consumption of
                date/time values. </para>
            <para>The system timezone is in UTC. MySQL converts
                TIMESTAMP values from the current time zone to UTC for
                storage, and back from UTC to the current time zone
                for retrieval. This does not occur for other types,
                such as DATETIME. </para>
            <example>
                <title>&Deployment; Service Date/Time Format</title>
                <programlisting>yyyy-MM-dd'T'HH:mm:ssZ</programlisting>
                <para>See the table below for a description of the
                    date/time format codes.</para>
                <para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have
                    the following format:</para>
                <programlisting>2011-05-19T08:07:08-05:00</programlisting>
            </example>
            <table rules="all">
                <caption>Explanation of Date/Time Format
                    Codes</caption>
                <thead>
                    <tr>
                        <td>Code</td>
                        <td>Description</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>yyyy</td>
                        <td>Four digit year</td>
                    </tr>
                    <tr>
                        <td>MM</td>
                        <td>Two digit month</td>
                    </tr>
                    <tr>
                        <td>dd</td>
                        <td>Two digit day of month</td>
                    </tr>
                    <tr>
                        <td>T</td>
                        <td>Separator for date/time</td>
                    </tr>
                    <tr>
                        <td>HH</td>
                        <td>Two digit hour of day (00-23)</td>
                    </tr>
                    <tr>
                        <td>mm</td>
                        <td>Two digit minutes of hour</td>
                    </tr>
                    <tr>
                        <td>ss</td>
                        <td>Two digit seconds of the minute</td>
                    </tr>
                    
                    <tr>
                        <td>Z</td>
                        <td>RFC-822 timezone</td>
                    </tr>
                </tbody>
            </table>
        </section>
        <section xml:id="DB_faults">
            <title>Faults</title>
            <para> The &Deployment; Service returns the following
                error codes: </para>
            <informaltable rules="all">
                <thead>
                    <tr align="center">
                        
                        <td colspan="1">Error Code</td>
                        <td colspan="3">Description</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        
                        <td colspan="1">400 Bad Request</td>
                        <td colspan="3">Invalid parameter values,
                            un-parsable data, or missing required
                            values.</td>
                    </tr>
                    <tr>
                        
                        <td colspan="1">404 Not Found</td>
                        <td colspan="3">The stack or resource cannot
                            be found.</td>
                    </tr>
                    <tr>
                        
                        <td colspan="1">409 Conflict</td>
                        <td colspan="3">Invalid action is requested
                            for the current stack status; more than
                            one object exists for the specified
                            non-unique identifier.</td>
                    </tr>
                    <tr>
                        
                        <td colspan="1">500 Internal Server Error</td>
                        <td colspan="3">Reverting the previously
                            failed action encountered an error, an
                            operation failed on one or more resources,
                            an unexpected error occurred.</td>
                    </tr>
                </tbody>
            </informaltable>
            <remark security="writeronly">Reviewer: Need new
                orchestration examples to replace the fault response
                examples below.</remark>
            <para security="writeronly">The following two <code>instanceFault</code>
                examples show errors when the server has erred or
                cannot perform the requested operation:</para>
            <para security="writeronly"> The error code (<code>code</code>) is returned in
                the body of the response for convenience. The
                    <code>message</code> element returns a
                human-readable message that is appropriate for display
                to the end user. The <code>details</code> element is
                optional and may contain information that is useful
                for tracking down an error, such as a stack trace. The
                    <code>details</code> element may or may not be
                appropriate for display to an end user, depending on
                the role and experience of the end user.</para>
            <para security="writeronly">The fault's root element (for example,
                    <code>instanceFault</code>) may change depending
                on the type of error. </para>
            <para security="writeronly"><?rax-fo keep-with-next?>The following two
                    <code>badRequest</code> examples show errors when
                the volume size is invalid:</para>
            <para security="writeronly">  The next two examples show
                    <code>itemNotFound</code> errors:</para>
        </section>
        <section xml:id="stack_status_dle264">
            <title>Stack Status</title>
            <para><?rax-fo keep-with-next?>Stacks and resources have a
                state and a status as described in the lists that
                follow:</para>
            <para>State:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>INIT &ndash; (Resources only) The resource
                        has not been provisioned.</para>
                </listitem>
                <listitem>
                    <para>CREATE &ndash; The stack/resource is
                        new.</para>
                </listitem>
                <listitem>
                    <para>UPDATE &ndash; The stack/resource is
                        changed.</para>
                </listitem>
                <listitem>
                    <para>DELETE &ndash; The stack/resource is
                        deleted.</para>
                </listitem>
                <listitem>
                    <para>ROLLBACK &ndash; A previously failed change
                        is being reverted.</para>
                </listitem>
                <listitem>
                    <para>SUSPEND &ndash; (Stacks only) The stack is
                        suspended.</para>
                </listitem>
                <listitem>
                    <para>RESUME &ndash; (Stacks only) The stack is
                        resumed.</para>
                </listitem>
            </itemizedlist>
            <para>Status:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>IN-PROGRESS &ndash; The operation is in
                        progress.</para>
                </listitem>
                <listitem>
                    <para>COMPLETE &ndash; The operation is
                        compete.</para>
                </listitem>
                <listitem>
                    <para>FAILED &ndash; The operation failed.</para>
                </listitem>
            </itemizedlist>
            <para>So, if you create a new stack and something goes
                wrong, your stack would be CREATE FAILED. One or more
                resources of that stack may be in the following
                states:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>INIT COMPLETE</para>
                </listitem>
                <listitem>
                    <para>CREATE FAILED</para>
                </listitem>
                <listitem>
                    <para>CREATE COMPLETE</para>
                </listitem>
            </itemizedlist>
        </section>
    </chapter>
    
    <chapter xml:id="API_Operations_dle7023">
        <title>API Operations</title>
        <para>This section describes the Orchestration API
            operations.</para>
        <remark security="writeronly">Reviewer: please give me a list
            of section titles to use for dividing up the API calls
            into related sections.</remark>
        <remark security="writeronly">Reviewer: please give me the Error Response Codes for
            each of the API calls.</remark>
        <wadl:resources
            href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"
            xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
    </chapter>
    <glossary>
        <title>Glossary</title>
        <glossentry xml:id="resource-d1e019">
            <glossterm>resource</glossterm>
            <glossdef>
                <para>A resource is a template artifact that
                    represents some component of your desired
                    architecture (a Nova server, a group of scaled
                    servers, a Cinder volume, some configuration
                    management system, and so forth).</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="stack-d1e017">
            <glossterm>stack</glossterm>
            <glossdef>
                <para>A stack is a group of resources (servers, load
                    balancers, databases, and so forth) combined to
                    fulfill a useful purpose. A stack is a set of
                    resources that can be deployed. A stack contains a
                    template and generates resources to run the
                    application framework or component
                    specified.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="template-d1e016">
            <glossterm>template</glossterm>
            <glossdef>
                <para>An &Deployment; template is a portable file,
                    written in a user-readable language, that
                    describes how a set of resources should be
                    assembled and what software should be installed in
                    order to produce a working deployment. The
                    template specifies what resources should be used,
                    what attributes can be set, and other parameters
                    that are critical to the successful, repeatable
                    automation of a specific application
                    deployment.</para>
            </glossdef>
        </glossentry>
    </glossary>
</book>
