Difference between revisions of "Heat/Open API"

Revision as of 01:09, 12 April 2013

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

@@ Line 1: / Line 1: @@
-== DRAFT ONLY - WORK IN PROGRESS ==
+== Proposal Only ==
-Please recognize that this is only a '''proposed''' DSL to be considered for development. This is NOT YET IMPLEMENTED.
+Please recognize that this is only a proposed DSL to be considered for development. This is NOT YET IMPLEMENTED.
 See: [https://blueprints.launchpad.net/heat/+spec/open-api-dsl Launchpad Blueprint for Open API/DSL]