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
Note: :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 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
 * 1) If the server is started with --with-simulator, the following calls are available:

Full Lifecycle with API Use Case
This section details all the necessary API calls a client (such as Horizon) would need to implement the ability to select a Heat Blueprint, launch it, monitor progress, and then delete it.

CALL 1: Get list of Heat Blueprints
Request: GET /v1/{tenant_id}/blueprints/.json HTTP/1.1 X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663 Host: heat.openstack.org

Note: Paginated collections use when we have a large number of blueprints.

Response Example:

> HTTP/1.1 200 OK > Content-Type: application/json;charset=utf-8 > Content-Length: 1587 > Date: Mon, 08 Apr 2013 01:26:00 GMT {    "38476ACF45F6745F223452E": { "blueprint": { "id": "38476ACF45F6745F223452E", "version": "1.0.0", "name": "WordPress", "options": { "region": { "default": "ORD", "required": true, "type": "string", ...               }, ...           },          "services": ..., ...     },     "environment": ..., ...    }, ... }

CALL 2: Launch a deployment
Request Description:

Combine the options the user supplies into an `inputs` object. Add that to the blueprint object and POST the combined object.

Request (to Heat):

POST /{tenant_id}/deployments/.json HTTP/1.1 X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663 Host: heat.openstack.org Content-type: application/json {   "name": "My Blog", "blueprint": …, "environment": …, "inputs": { "region": "ORD", ...   } }

Response Description:

The Location header will return asynchronously to provide the deployment ID ASAP.

display-outputs: will contain outputs to display such as the application URL. Additional information, such as the IP for a URL, can also be returned so clients can show information such as a bash script for modifying the hosts file until DNS propagates.

We would like to support pluggable underlying implementations (workflows, celery canvases, distributed state engines, etc…). To support client tools in a generic way, the API will return [RFC5988](http://tools.ietf.org/html/rfc5988) Link headers where appropriate.

Response Example: > HTTP/1.1 200 OK > Content-Type: application/json;charset=utf-8 > Content-Length: 1587 > Date: Mon, 08 Apr 2013 01:26:00 GMT > Location: /{tenant_id}/deployments/3554aaa > Link: \; rel="workflow"; title="Deploy xxx" {  "id": "3554aaa", "status": "PLANNING", "display-outputs": { "Admin URL": { "type": "url", "value": "http://blog.openstack.com/admin", "ipv4": "4.4.4.4", "ipv6": "f000::08", "order": 1 },     "Username": { "type": "string", "value": "wp_user", "order": 2 }  }, ... }

CALL 3: Get Deployment
This is used to get the status as a deployment is launched and also to retieve data about an existing deployment.

Request (to Heat):

GET /{tenant_id}/deployments/3554aaa.json HTTP/1.1 X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663 Host: heat.openstack.org

Response Description:

Response Fields:


 * status: will reflect the overall deployment status.
 * operation: will contain information about the ongoing operation (independent of the subsystem running it). The following fields will always be provided:
 * operation.type: deploy, add node, delete, etc…
 * operation.estimated-duration: total seconds expected from start to finish
 * operation.elapsed: total seconds elapsed since start (this is not a valid time estimate. It is a completion estimate calculated based on task estimated durations and task completion status)
 * operation.tasks: total number of tasks to complete
 * operation.complete: total number of tasks already completed
 * operation.link: a link to the operation - this would be implementation specific

Note: see  for example of error condition


 * resources: hash of resources. For each resource:
 * resource.provider: nova, databases, load-balancers, etc… the service used to create it.
 * resource.dns-name: the name of the resource
 * resource.status: the status of the resource (ex. BUILD, CONFIGURE, ACTIVE, etc…)
 * resource.service: the blueprint service the resource is in
 * resource.instance: contains information like id, flavor, image, region, etc.

Response Example: > HTTP/1.1 200 OK > Content-Type: application/json;charset=utf-8 > Content-Length: 1587 > Date: Mon, 08 Apr 2013 01:26:00 GMT {  "id": "3554aaa", "status": "LAUNCHED", "operation": { "type": "deploy", "status": "IN PROGRESS", "estimated-duration": 2400, "elapsed": 1702, "tasks": 175, "complete": 100, "link": "/{tenant_id}/transactions/982h3f28937h4f23847" },  "resources": { "0": {      "type": "compute", "status": "CONFIGURE", "provider": "nova", "service": "web", "dns-name": "web01.domain.com", "instance": { "id": 29857645, "region": "ORD", "flavor": 4, "image": 119 }    },     "1": {...},     "2": {…},     "3": {…},     "4": {…},     ...     },     "display-outputs": { "Admin URL": { "type": "url", "value": "http://blog.openstack.org/admin", "ipv4": "4.4.4.4", "ipv6": "f000::08", "order": 1 },    "Username": { "type": "string", "value": "wp_user", "order": 2 }  } }

CALL 4: List Deployments
Request (to Heat): GET /{tenant_id}/deployments/.json HTTP/1.1 X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663 Host: heat.openstack.org

Response Description:

Response Fields:


 * key: is the ID.
 * name: the name of the deployment
 * status: the status as a string
 * operation: will contain information about the ongoing operation (independent of the pluggable subsystem running it).

In the case of an error condition:


 * operation.status: ERROR. Note this differs from deployment status.
 * operation.error-message: the short, one-line description of the error
 * operation.error-help: detailed error information
 * operation.retryable: can this error be retried?
 * operation.retry-link: the URL to call to retry

Note: same for  and

Response Example: > HTTP/1.1 200 OK > Content-Type: application/json;charset=utf-8 > Content-Length: 1587 > Date: Mon, 08 Apr 2013 01:26:00 GMT "938f573645": { "status": "DEPLOYING", "operation": { "type": "deploy", "status": "IN PROGRESS", "estimated-duration": 2400, "elapsed": 1702, "tasks": 175, "complete": 100, "link": "/{tenant_id}/transactions/982h3f28937h4f23847" }, }, … },  "87747464ds": { "name": "My Blog", "status": "DELETING", "operation": { "type": "deploy", "status": "ERROR", "error-message": "You reached your maximum number of Cloud Databases", "error-help": "Please refer to the [knowledge center](http://kc-link.com) to fix this", "retriable": true, //can be retried "retry-link": "/{tenant_id}/transactions/982h3f28937h4f23847/+retry", "resumable": true, "resume-link": "/{tenant_id}/transactions/982h3f28937h4f23847/+resume", "estimated-duration": 2400, "elapsed": 1702, "tasks": 175, "complete": 100, "link": "/{tenant_id}/transactions/982h3f28937h4f23847" },    "blueprint": { "meta-data": ... },    …   },   … }

CALL 5: Delete Deployment
Request (to Heat):

DELETE /{tenant_id}/deployments/938f573645.json HTTP/1.1 X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663 Host: heat.openstack.org

Response Description: > HTTP/1.1 202 OK > Content-Type: application/json;charset=utf-8 > Content-Length: 1587 > Date: Mon, 08 Apr 2013 01:26:00 GMT > Link: \; rel="celery canvas"; title="Delete xxx" {  "938f573645": { "status": "DELETING", "operation": { "status": "IN PROGRESS", "link": "/{tenant_id}/canvases/982h3f28937h4f23847", ... }