Jump to: navigation, search

Difference between revisions of "Heat/GrizzlySummit/HeatApiDraftDiscussion"

m (Text replace - "__NOTOC__" to "")
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NOTOC__
+
 
 
Session Lead: Steven Dake
 
Session Lead: Steven Dake
  
Line 9: Line 9:
  
 
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.

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