Jump to: navigation, search

Heat/Open API

< Heat
Revision as of 23:59, 10 April 2013 by Adrian Otto (talk | contribs) (List of all calls)


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.


  • 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)


  • 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.

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.


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:


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