Jump to: navigation, search

Difference between revisions of "Heat/GrizzlySummit/HeatApiDraftDiscussion"

(Add current API docs)
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/heat-api/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 [RFC2626](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3). 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

Revision as of 14:40, 11 October 2012

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/heat-api/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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3). 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
Retrieved from "https://wiki.openstack.org/w/index.php?title=Heat/GrizzlySummit/HeatApiDraftDiscussion&oldid=7570"