ReST API: Add some simple API documentation

Change-Id: I6b3ff5a46e0ba836634cc21cf7ee8945a18a6a3a
Signed-off-by: Zane Bitter <zbitter@redhat.com>
This commit is contained in:
Zane Bitter 2012-10-10 18:22:01 +02:00
parent a553fc2ba5
commit 64fc539afc

163
docs/api.md Normal file
View File

@ -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