diff options
author | Zane Bitter <zbitter@redhat.com> | 2012-10-10 18:22:01 +0200 |
---|---|---|
committer | Zane Bitter <zbitter@redhat.com> | 2012-10-10 18:27:31 +0200 |
commit | 64fc539afcd2adfe8d8698bb6a838a22fc3a132e (patch) | |
tree | ffbae12f9bb2813eaa6ccc1dcecb7b63ce500f61 /docs | |
parent | a553fc2ba55170fc27f2d4e6c5b44d6570523bda (diff) | |
download | heat-64fc539afcd2adfe8d8698bb6a838a22fc3a132e.tar.gz |
ReST API: Add some simple API documentation
Change-Id: I6b3ff5a46e0ba836634cc21cf7ee8945a18a6a3a
Signed-off-by: Zane Bitter <zbitter@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/api.md | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 000000000..44305a7b0 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,163 @@ +Heat OpenStack API Reference +============================ + +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 |