diff --git a/doc/docbkx/api-ref/pom.xml b/doc/docbkx/api-ref/pom.xml index 3147fce7ef..b53cba37d7 100644 --- a/doc/docbkx/api-ref/pom.xml +++ b/doc/docbkx/api-ref/pom.xml @@ -1,7 +1,10 @@ - + + + + 4.0.0 org.openstack.identity @@ -36,7 +39,7 @@ UTF-8 - 1.5.1 + 1.11.0 @@ -48,7 +51,7 @@ g1 - generate-html + generate-webhelp generate-sources @@ -67,7 +70,7 @@ reviewer openstack - 1 + 2 true diff --git a/doc/docbkx/api-ref/src/docbkx/api-ref.xml b/doc/docbkx/api-ref/src/docbkx/api-ref.xml index ab1ca4aef8..a336772291 100644 --- a/doc/docbkx/api-ref/src/docbkx/api-ref.xml +++ b/doc/docbkx/api-ref/src/docbkx/api-ref.xml @@ -1,24 +1,527 @@ - - - Heat API - - 2012 - - - - - - - Heat - - - - + + + + + + GET'> + PUT'> + POST'> + DELETE'> + + + + + + + + + + + + +]> + + OpenStack Orchestration API v1 Reference + + + + + + + + + OpenStack LLC + + + + 2012 + 2013 + OpenStack LLC + + API v1 + OpenStack Orchestration + 2013-10-03 + + + Copyright details are filled in by the template. + + + + 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. + Reviewer: Can you provide me + with a high-level Orchestration architecture diagram that + I can add to this section? + 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 + <emphasis role="strong" + >bold</emphasis>) + 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
FormatAccept HeaderQuery ExtensionDefault
JSONapplication/json.jsonYes
YAMLapplication/yaml.yamlNo
+ Reviewer: need new examples + below: one for "Request with Headers: JSON" and one + for "Request with Headers: YAML". + 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
CodeDescription
yyyyFour digit year
MMTwo digit month
ddTwo digit day of month
TSeparator for date/time
HHTwo digit hour of day (00-23)
mmTwo digit minutes of hour
ssTwo digit seconds of the minute
ZRFC-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. + + + + Reviewer: Need new + orchestration examples to replace the fault response + examples below. + 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 – (Resources only) The resource + has not been provisioned. + + + CREATE – The stack/resource is + new. + + + UPDATE – The stack/resource is + changed. + + + DELETE – The stack/resource is + deleted. + + + ROLLBACK – A previously failed change + is being reverted. + + + SUSPEND – (Stacks only) The stack is + suspended. + + + RESUME – (Stacks only) The stack is + resumed. + + + Status: + + + IN-PROGRESS – The operation is in + progress. + + + COMPLETE – The operation is + compete. + + + FAILED – 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. + Reviewer: please give me a list + of section titles to use for dividing up the API calls + into related sections. + Reviewer: please give me the Error Response Codes for + each of the API calls. + + + + 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. + + + + diff --git a/doc/docbkx/api-ref/src/wadls/heat-api/src/README.rst b/doc/docbkx/api-ref/src/wadls/heat-api/src/README.rst new file mode 100644 index 0000000000..3bb041e6e8 --- /dev/null +++ b/doc/docbkx/api-ref/src/wadls/heat-api/src/README.rst @@ -0,0 +1,9 @@ +========= +HEAT wadl +========= + +The original heat wadl (heat-api-1.0.wadl) and the samples have now been deleted from this repository. + +The wadl has been renamed and migrated to the following repo location along with the samples: +https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl + diff --git a/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl b/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl deleted file mode 100644 index 53e2ed3ba4..0000000000 --- a/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl +++ /dev/null @@ -1,389 +0,0 @@ - - - - - - - - - - - -

- The unique identifier of the tenant or account. -

- - - - - - - - - -

- The name of an existing stack. -

- - - - - - - - - - - - - - -

- The unique identifier of an existing stack. -

- - - - - - - - - - - - - - - -

- The name of a resource in the stack. -

- - - - - - - - - - - - - - -

- The unique identifier of an event related to the resource in the stack. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Get a list of active stacks.

- - - - - - - - -

Create a Stack.

- - - - -

- The name of the stack to create. -

- - - -

- The URL of the template to instantiate. -

- This is ignored if the template is supplied inline. -

- - - -

- A JSON template to instantiate. -

- This takes precedence over the Template URL if both are supplied. -

- - - -

- A JSON envionment for the stack. -

- - - -

- User-defined parameter names to pass to the template. -

- - - -

- User-defined parameter values to pass to the template. -

- - - -

- The timeout for stack creation in minutes. -

- - - - - - - - - - - - - - -

Find the canonical URL for a stack with a given name.

-

This operation also works - with verbs other than GET, so you can also use it to perform - PUT and DELETE operations on a current stack. Just set your - client to follow redirects. Note that when redirecting, the - request method should not change, as defined in RFC2626. - However, in many clients the default behaviour is to change the - method to GET when receiving a 302 because this behaviour is - ubiquitous in web browsers.

- - - - - - - -

Get data about a stack.

- - - - - - - - -

Retrieve a stack's template.

- - - - - - - - -

Update a Stack.

- - - - -

- The URL of the template to instantiate. -

- This is ignored if the template is supplied inline. -

- - - -

- A JSON template to instantiate. -

- This takes precedence over the Template URL if both are supplied. -

- - - -

- A JSON envionment for the stack. -

- - - -

- User-defined parameter names to pass to the template. -

- - - -

- User-defined parameter values to pass to the template. -

- - - -

- The timeout for stack creation in minutes. -

- - - - - - - - - - - - - - -

Delete a stack.

- - - - - - - -

Update a Stack.

- - - - -

- The URL of the template to instantiate. -

- This is ignored if the template is supplied inline. -

- - - -

- A JSON template to instantiate. -

- This takes precedence over the Template URL if both are supplied. -

- - - - - - - - - - - - - - - -

Get a list of the template resource types that are supported.

- - - - - - - - -

Find the canonical URL for the resource list of a stack with a given name.

- - - - - - - -

Get a list of resources in a stack.

- - - - - - - - -

Get data about a resource.

- - - - - - - - -

Get data a resource's metadata.

- - - - - - - - -

Find the canonical URL for the event list of a stack with a given name.

- - - - - - - -

Get a list of events for a stack.

- - - - - - - - -

Get a list of events for a stack resource.

- - - - - - - - -

Get data about an event.

- - - - - - - diff --git a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_create.json b/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_create.json deleted file mode 100644 index 6b8fab1011..0000000000 --- a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_create.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "stack_name": "{stack_name}", - "template_url": "{template_url}", - "parameters": { - "param_name-1": "param_value-1", - "param_name-2": "param_value-2" - }, - "timeout_mins": {timeout_mins} -} diff --git a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_update.json b/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_update.json deleted file mode 100644 index 1ef9a7eaf0..0000000000 --- a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/stack_update.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "template_url": "{template_url}", - "parameters": { - "param_name-1": "param_value-1", - "param_name-2": "param_value-2" - }, - "timeout_mins": {timeout_mins} -} diff --git a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/template_validate.json b/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/template_validate.json deleted file mode 100644 index 0a90617f45..0000000000 --- a/doc/docbkx/api-ref/src/wadls/heat-api/src/samples/template_validate.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "template_url": "{template_url}" -}