Difference between revisions of "Heat/Open API"
Adrian Otto (talk | contribs) (→GET) |
Adrian Otto (talk | contribs) (→Heat Open API Overview) |
||
Line 14: | Line 14: | ||
Note: Not all verbs on all paths. | Note: Not all verbs on all paths. | ||
+ | |||
+ | == GET == | ||
+ | * Will sometimes add the object ID and tenant ID if the underlying store does not provide them. | ||
+ | ** This is so that the object can be identified when parsed later. | ||
== POST & PUT == | == POST & PUT == |
Revision as of 00:01, 11 April 2013
Contents
DRAFT ONLY - WORK IN PROGRESS
Please recognize that this is only a proposed DSL to be considered for development. This is NOT YET IMPLEMENTED.
Heat Open API Overview
This is a REST API to support the proposed Heat/DSL. The API is a REST HTTP API. It supports POST, PUT, GET, DELETE on:
- /components[/:id]
- /blueprints[/:id]
- /environments[/:id]
- /deployments[/:id]
- /workflows[/:id]
- /providers[/:id]
Note: Not all verbs on all paths.
GET
- Will sometimes add the object ID and tenant ID if the underlying store does not provide them.
- This is so that the object can be identified when parsed later.
POST & PUT
- PUT - Updates without taking any action or side effects on other resources. The only permitted side-effect is on the resource itself (for example, updating a last-modified field).
- POST - Can update and/or trigger actions (like actual server deployments) and can accept partial objects.
The Semantics are:
POST /objects (without ID)
- Creates a new object. ID is generated by Heat and returned in the Location header.
- Use it to create objects without fear of ID conflicts
POST /objects/:id
- Update an existing object. Partial updates are supported (i.e. I can POST only the name to rename the object). Could trigger actions, like running a workflow.
- Use it to modify parts of an object.
PUT /objects/:id
- Overwrites the object completely. Does not trigger side effects, but will validate data (especially id and tenant_id fields).
- Use it to store something in Heat (ex. a deployment exported from another instance of Heat)
DELETE /objects/:id
- Will trigger deletion of the object.
- May also trigger deletion of all related running instances started by Heat for the given assembly.
JSON, YAML, and XML
Objects are returned as JSON by default, but YAML is also supported (content-type: application/x-yaml) HTML output is also supported if the server is started with a `--with-ui` parameter.
XML is not yet supported.
Special Cases and Considerations
All objects should have a root key with the name of the class. Ex. `{"blueprint": {"id": 1}}`. However, Heat will permit objects without the root if they are provided. Example:
PUT /blueprints/2 {"id": 2}
Heat will fill in the id, status, tenant_id, and creation date of posted objects. For puts, these value must be supplied and must be correct (i.e. matching the tenant and id in the URL).
YAML supports references within a document. If a deployment is in YAML format and is using references, the references can be provided under a key called 'includes'. This can be used, for example, to create a new deployment passing in all the necessary components, blueprints, environments, etc... (or references to them).
Some commands can be issued with a '+command' URL. Example:
/workflows/wf1000/+execute
All calls are supported flat off of the root or under a tenant ID. Calls off of the root require administrative privileges and will return all objects from all tenants (ex. /environments vs /T1000/environments)
All calls to GET /deployments and GET /workflows may be optionally paginated by offset and limit.
List of All Calls
- tid* is the tenant ID and is optional.
GET/POST [/:tid]/environments PUT/GET/POST [/:tid]/environments/:id GET [/:tid]/environments/:id/providers GET [/:tid]/environments/:id/providers/:pid GET [/:tid]/environments/:id/providers/:pid/catalog GET [/:tid]/environments/:id/providers/:pid/catalog/:cid GET/POST [/:tid]/blueprints PUT/GET/POST [/:tid]/blueprints/:id GET [/:tid]/deployments/[?offset=OFFSET&limit=LIMIT] POST [/:tid]/deployments PUT/GET/POST [/:tid]/deployments/:id POST [/:tid]/deployments/+parse POST [/:tid]/deployments/+preview GET [/:tid]/deployments/:id/status GET [/:tid]/workflows/[?offset=OFFSET&limit=LIMIT] POST [/:tid]/workflows PUT/GET/POST [/:tid]/workflows/:id GET [/:tid]/workflows/:id/status POST [/:tid]/workflows/:id/+execute GET/POST [/:tid]/workflows/:id/tasks/:task_id POST [/:tid]/workflows/:id/tasks/:task_id/+execute POST [/:tid]/workflows/:id/tasks/:task_id/+resubmit GET [/:tid]/providers GET [/:tid]/providers/:pid GET [/:tid]/providers/:pid/catalog GET [/:tid]/providers/:pid/catalog/:cid # If the server is started with --with-admin, the following calls are available to admin users: GET /admin/status/celery GET /admin/status/libraries # If the server is started with --with-simulator, the following calls are available: POST [/:tid]/deployments/simulate GET [/:tid]/deployments/simulate GET [/:tid]/workflows/simulate/status #progresses the workflow by one task GET [/:tid]/workflows/simulate/status?complete #completes the workflow