# OpenStack Orchestration API v1 Reference

OpenStack LLC
2012
2013
OpenStack LLC
API v1
OpenStack Orchestration 2013-10-03

This document is intended for software developers interested in developing applications using the OpenStack Orchestration Application Programming Interface (API).

2013-10-03

- Initial review.

## Overview

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.

We welcome feedback, comments, and bug reports at https://bugs.launchpad.net/heat.

### Intended Audience

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.

To use the information provided here, you should first have a general understanding of the &Deployment; service. You should also be familiar with:

- Other OpenStack services applicable to your cloud application architecture (Nova, Cinder, Neutron, and so forth)

- RESTful web services

- JSON and/or YAML data serialization formats

### Document Change History

This version of the Reference replaces and obsoletes all previous versions. The most recent changes are described in the table below:

### Additional Resources

You can find information for developing templates in the Heat Orchestration Template (HOT) Specification at http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec.

You can find example templates at https://github.com/heat-ci/heat-prod-templates/tree/master/example.

For information about OpenStack services, refer to http://docs.openstack.org.

## Concepts

To use &Deployment; effectively, you should understand several key concepts:

### Stack

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.

### Resource

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).

### Template

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.

## General API Information

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.

### Authentication

The &Deployment; Service supports standard Keystone authentication. For more information, refer to the OpenStack Identity Service API v2.0 Reference. Please contact your provider for additional details on how to authenticate against this API.

### Contract Version

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.

#### Example Request URL (contract version in bold)

    https://openstack.example.com/v1/1234

This document pertains to contract version 1.

### Request/Response Types

The &Deployment; API supports both the JSON and YAML data serialization formats. The request format is specified using the `Content-Type` header and is required for calls that have a request body. The response format can be specified in requests either by using the `Accept` header or by adding a `.yaml` or `.json` 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 `Accept` header and a query extension, the query extension takes precedence.

Response Formats
Format | Accept Header | Query Extension | Default
--- | --- | --- | ---
JSON | application/json | .json | Yes
YAML | application/yaml | .yaml | No

In the request example below, notice that `Content-Type` is set to `application/json`, but `application/yaml` is requested via the `Accept` header:

Therefore a YAML response format is returned:

### Date/Time Format

The &Deployment; Service uses an ISO-8601 compliant date format for the display and consumption of date/time values.

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.

#### &Deployment; Service Date/Time Format

    yyyy-MM-dd'T'HH:mm:ssZ

See the table below for a description of the date/time format codes.

May 19th, 2011 at 8:07:08 AM, GMT-5 would have the following format:

    2011-05-19T08:07:08-05:00

Explanation of Date/Time Format Codes
Code | Description
--- | ---
yyyy | Four digit year
MM | Two digit month
dd | Two digit day of month
T | Separator for date/time
HH | Two digit hour of day (00-23)
mm | Two digit minutes of hour
ss | Two digit seconds of the minute
Z | RFC-822 timezone

### Faults

The &Deployment; Service returns the following error codes:

Error Code | Description
--- | ---
400 Bad Request | Invalid parameter values, un-parsable data, or missing required values.
404 Not Found | The stack or resource cannot be found.
409 Conflict | Invalid action is requested for the current stack status; more than one object exists for the specified non-unique identifier.
500 Internal Server Error | Reverting the previously failed action encountered an error, an operation failed on one or more resources, an unexpected error occurred.

The following two `instanceFault` examples show errors when the server has erred or cannot perform the requested operation:

The error code (`code`) is returned in the body of the response for convenience. The `message` element returns a human-readable message that is appropriate for display to the end user. The `details` element is optional and may contain information that is useful for tracking down an error, such as a stack trace. The `details` element may or may not be appropriate for display to an end user, depending on the role and experience of the end user.

The fault's root element (for example, `instanceFault`) may change depending on the type of error.

The following two `badRequest` examples show errors when the volume size is invalid:

The next two examples show `itemNotFound` errors:

### Stack Status

Stacks and resources have a state and a status as described in the lists that follow:

State:

- INIT &ndash; (Resources only) The resource has not been provisioned.

- CREATE &ndash; The stack/resource is new.

- UPDATE &ndash; The stack/resource is changed.

- DELETE &ndash; The stack/resource is deleted.

- ROLLBACK &ndash; A previously failed change is being reverted.

- SUSPEND &ndash; (Stacks only) The stack is suspended.

- RESUME &ndash; (Stacks only) The stack is resumed.

Status:

- IN-PROGRESS &ndash; The operation is in progress.

- COMPLETE &ndash; The operation is compete.

- FAILED &ndash; The operation failed.

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:

- INIT COMPLETE

- CREATE FAILED

- CREATE COMPLETE

## API Operations

This section describes the Orchestration API operations.

## Glossary

resource

  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).

stack

  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.

template

  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.