Heat/Open API

Proposal Only

Please recognize that this is only a proposed DSL to be considered for development. This is NOT YET IMPLEMENTED.

See: Launchpad Blueprint for Open API/DSL

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 (content-type: application/x-yaml) and XML are also 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-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