Difference between revisions of "Heat/GrizzlySummit/HeatApiDraftDiscussion"
m (Text replace - "__NOTOC__" to "") |
|||
(5 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
− | |||
Session Lead: Steven Dake | Session Lead: Steven Dake | ||
+ | |||
Session Title: Heat Orchestration API draft design session | Session Title: Heat Orchestration API draft design session | ||
+ | |||
Session Description: | Session Description: | ||
− | Overview of the template format currently implemented in heat. Overview | + | |
− | of the API heat provides for operating on templates. | + | Overview of the template format currently implemented in heat. Overview of the API heat provides for operating on templates. |
In this design session, expect 75% of time spent in open community design session on improvements to API and template model. | In this design session, expect 75% of time spent in open community design session on improvements to API and template model. | ||
+ | |||
+ | == Heat [[OpenStack]] API Reference == | ||
+ | |||
+ | ''See https://github.com/openstack/heat/blob/master/docs/api.md for the latest version.'' | ||
+ | |||
+ | === List Stacks === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | GET /v1/{tenant_id}/stacks | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `tenant_id` The unique identifier of the tenant or account | ||
+ | |||
+ | === Create Stack === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | POST /v1/{tenant_id}/stacks | ||
+ | |||
+ | { | ||
+ | "stack_name": "{stack_name}", | ||
+ | "template_url": "{template_url}", | ||
+ | "parameters": { | ||
+ | "{key1}": "{value1}", | ||
+ | "{key2}": "{value2}" | ||
+ | }, | ||
+ | "timeout_mins": {timeout_mins} | ||
+ | } | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `tenant_id` The unique identifier of the tenant or account | ||
+ | * `stack_name` The name of the stack to create | ||
+ | * `template_url` The URL of the template to instantiate | ||
+ | * `template` A JSON template to instantiate - this takes precendence over the `template_url` if both are supplied | ||
+ | * `keyn`, `valuen` User-defined parameters to pass to the Template | ||
+ | * `timeout_mins` The timeout for stack creation in minutes | ||
+ | |||
+ | Result: | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | HTTP/1.1 201 Created | ||
+ | Location: http://heat.example.com:8004/v1/{tenant_id}/stacks/{stack_name}/{stack_id} | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | === Find Stack ID === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | GET /v1/{tenant_id}/stacks/{stack_name} | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `stack_name` The name of the stack to look up | ||
+ | |||
+ | Result: | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | HTTP/1.1 302 Found | ||
+ | Location: http://heat.example.com:8004/v1/{tenant_id}/stacks/{stack_name}/{stack_id} | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | 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 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3 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 Stack Data === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id} | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `stack_name` The name of the stack to look up | ||
+ | * `stack_id` The unique identifier of the stack to look up | ||
+ | |||
+ | === Retrieve Stack Template === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `stack_name` The name of the stack to look up | ||
+ | * `stack_id` The unique identifier of the stack to look up | ||
+ | |||
+ | === Update Stack === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id} | ||
+ | |||
+ | { | ||
+ | "template_url": "{template_url}", | ||
+ | "parameters": { | ||
+ | "{key1}": "{value1}", | ||
+ | "{key2}": "{value2}" | ||
+ | }, | ||
+ | "timeout_mins": {timeout_mins} | ||
+ | } | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `tenant_id` The unique identifier of the tenant or account | ||
+ | * `stack_name` The name of the stack to create | ||
+ | * `stack_id` The unique identifier of the stack to look up | ||
+ | * `template_url` The URL of the updated template | ||
+ | * `template` An updated JSON template - this takes precendence over the `template_url` if both are supplied | ||
+ | * `keyn`, `valuen` User-defined parameters to pass to the Template | ||
+ | * `timeout_mins` The timeout for stack creation in minutes | ||
+ | |||
+ | Result: | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | HTTP/1.1 202 Accepted | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | === Delete Stack === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id} | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `tenant_id` The unique identifier of the tenant or account | ||
+ | * `stack_name` The name of the stack to create | ||
+ | * `stack_id` The unique identifier of the stack to look up | ||
+ | |||
+ | Result: | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | HTTP/1.1 204 No Content | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | === Validate Template === | ||
+ | |||
+ | |||
+ | <pre><nowiki> | ||
+ | POST /v1/{tenant_id}/validate | ||
+ | |||
+ | { | ||
+ | "template_url": "{template_url}", | ||
+ | "parameters": { | ||
+ | "{key1}": "{value1}", | ||
+ | "{key2}": "{value2}" | ||
+ | } | ||
+ | } | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | Parameters: | ||
+ | |||
+ | * `tenant_id` The unique identifier of the tenant or account | ||
+ | * `template_url` The URL of the template to validate | ||
+ | * `template` A JSON template to validate - this takes precendence over the `template_url` if both are supplied. | ||
+ | * `keyn`, `valuen` User-defined parameters to pass to the Template |
Latest revision as of 23:29, 17 February 2013
Session Lead: Steven Dake
Session Title: Heat Orchestration API draft design session
Session Description:
Overview of the template format currently implemented in heat. Overview of the API heat provides for operating on templates.
In this design session, expect 75% of time spent in open community design session on improvements to API and template model.
Contents
Heat OpenStack API Reference
See https://github.com/openstack/heat/blob/master/docs/api.md for the latest version.
List Stacks
GET /v1/{tenant_id}/stacks
Parameters:
- `tenant_id` The unique identifier of the tenant or account
Create Stack
POST /v1/{tenant_id}/stacks { "stack_name": "{stack_name}", "template_url": "{template_url}", "parameters": { "{key1}": "{value1}", "{key2}": "{value2}" }, "timeout_mins": {timeout_mins} }
Parameters:
- `tenant_id` The unique identifier of the tenant or account
- `stack_name` The name of the stack to create
- `template_url` The URL of the template to instantiate
- `template` A JSON template to instantiate - this takes precendence over the `template_url` if both are supplied
- `keyn`, `valuen` User-defined parameters to pass to the Template
- `timeout_mins` The timeout for stack creation in minutes
Result:
HTTP/1.1 201 Created Location: http://heat.example.com:8004/v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Find Stack ID
GET /v1/{tenant_id}/stacks/{stack_name}
Parameters:
- `stack_name` The name of the stack to look up
Result:
HTTP/1.1 302 Found Location: http://heat.example.com:8004/v1/{tenant_id}/stacks/{stack_name}/{stack_id}
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 Stack Data
GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Parameters:
- `stack_name` The name of the stack to look up
- `stack_id` The unique identifier of the stack to look up
Retrieve Stack Template
GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template
Parameters:
- `stack_name` The name of the stack to look up
- `stack_id` The unique identifier of the stack to look up
Update Stack
PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id} { "template_url": "{template_url}", "parameters": { "{key1}": "{value1}", "{key2}": "{value2}" }, "timeout_mins": {timeout_mins} }
Parameters:
- `tenant_id` The unique identifier of the tenant or account
- `stack_name` The name of the stack to create
- `stack_id` The unique identifier of the stack to look up
- `template_url` The URL of the updated template
- `template` An updated JSON template - this takes precendence over the `template_url` if both are supplied
- `keyn`, `valuen` User-defined parameters to pass to the Template
- `timeout_mins` The timeout for stack creation in minutes
Result:
HTTP/1.1 202 Accepted
Delete Stack
DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Parameters:
- `tenant_id` The unique identifier of the tenant or account
- `stack_name` The name of the stack to create
- `stack_id` The unique identifier of the stack to look up
Result:
HTTP/1.1 204 No Content
Validate Template
POST /v1/{tenant_id}/validate { "template_url": "{template_url}", "parameters": { "{key1}": "{value1}", "{key2}": "{value2}" } }
Parameters:
- `tenant_id` The unique identifier of the tenant or account
- `template_url` The URL of the template to validate
- `template` A JSON template to validate - this takes precendence over the `template_url` if both are supplied.
- `keyn`, `valuen` User-defined parameters to pass to the Template