Jump to: navigation, search

Difference between revisions of "Mistral/RestAPI"

(Create an execution [POST])
(Update an execution [PUT])
Line 193: Line 193:
 
The only sensible field of an execution to updated is '''state'''. That way a user can manually suspend/resume the execution or completely stop it.
 
The only sensible field of an execution to updated is '''state'''. That way a user can manually suspend/resume the execution or completely stop it.
  
* '''URL:''' /workbooks/<workbook-name>/executions/<execution-id>
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Execution
 
* '''Returns:''' Execution

Revision as of 10:57, 26 May 2014

Mistral API v1.0

This API describes the ways of interacting with Mistral service via HTTP protocol using Representational State Transfer concept (ReST).

Media Types

Currently this API relies on JSON to represent resources states. Future specifications may also support YAML, XML or other types. The only one place where YAML is used is Mistral DSL for describing Mistral workbooks which contain tasks, dependencies and transitions between them, actions, triggers and other entities related to workflow execution.

Error States

The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

Application Root [/]

Application Root provides links to all possible API methods for Mistral. URLs for other resources described below are relative to Application Root.

Workbook [/workbooks/{name}]

Workbook describes tasks, dependencies and transitions between them, actions, triggers and other entities related to some particular business field. In other words, this is a definition of how tasks should be processed in a particular case and a set of rules describing how and when to run them. See Mistral DSL Specification for details.

A Workbook has the following attributes:

  • name
  • description
  • tags


Note that name is immutable. tags is a list of values associated with a workbook that a user can use to group workbooks by some criteria (deployment workbooks, Big Data processing workbooks etc.)

URL Parameters

  • name - Workbook name.

Model

{
    "name" : "my_deployment_workbook",
    "description" : "A set of tasks for deployment",
    "tags": ["deployment", "mc"]
}

Retrieve Workbook list [GET]

  • URL: /workbooks
  • Status: 200
  • Returns: List of workbooks
Response
{
    "workbooks": [
        {
            "name": "my_deployment_workbook",
            "description": "My deployment workbook",
            "tags": ["deployment", "mc"]
        }
    ]
}

Retrieve a single Workbook [GET]

  • URL: /workbooks/{workbook_name}
  • Status: 200
  • Returns: Workbook
Response
{
    "name": "my_deployment_workbook",
    "description": "My deployment workbook",
    "tags": ["deployment", "mc"]
}

Create a Workbook [POST]

To create a new Workbook simply provide a JSON structure containing attribute values.

  • URL: /workbooks
  • Status: 201
  • Returns: Created Workbook
Request (application/json)
{
    "name": "my_deployment_workbook",
    "description": "My deployment workbook",
    "tags": ["deployment", "mc"]
}

Update a Workbook [PUT]

To modify a workbook simply send a JSON structure containing values for corresponding mutable fields.

  • URL: /workbook/{workbook_name}
  • Status: 200
  • Returns: Updated Workbook
Request example
{
    "name": "my_deployment_workbook",
    "description": "My cool deployment workbook!",
    "tags": ["deployment", "mc", "new_tag"]
}

Delete a Workbook [DELETE]

  • URL: /workbook/{workbook_name}
  • Status: 204
  • Returns: No content

Workbook Definition [/workbook/{workbook_name}/definition]

Workbook definition is a YAML document (what is called "Mistral DSL") containing description of all entities of the workbook like action namespaces, workflow, triggers etc. See Mistral DSL Specification for details.

URL Parameters

  • workbook_name - Workbook name.

Retrieve a workbook definition [GET]

  • URL: /workbook/{workbook_name}/definition
  • Status: 200
  • Returns: Mistral DSL document

Upload a workbook definition [PUT]

  • URL: /workbook/{workbook_name}/definition
  • Status: 201
  • Returns: Mistral DSL document
  • Content-Type: text/plain

Execution [/workbooks/{workbook_name}/executions/{id}]

A particular workflow execution.

An Execution has the following attributes:

  • id
  • workbook_name
  • task
  • context
  • state


Note that id is immutable and automatically assigned by Mistral at creation time. task defines a task that the workflow should start with. context is a JSON structure containing workflow input values. state can take one of the following values:

  • IDLE
  • RUNNING
  • SUCCESS
  • ERROR
  • STOPPED
  • DELAYED

URL Parameters

  • workbook_name (string) - Workbook name.
  • id (string) - Execution id.

Model

{
    "id": "12304593450234",
    "workbook_name": "my_deployment_workbook",
    "task": "deploy_env",
    "context": {
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
    },
    "state": "RUNNING"
}

Retrieve Execution list [GET]

  • URL: /workbooks/{workbook-name}/executions
  • Status: 200
  • Returns: List of Executions

Retrieve a single execution [GET]

  • URL: /workbooks/{workbook-name}/executions/{execution-id}
  • Status: 200
  • Returns: Execution

Create an execution [POST]

To create a new execution simply provide a JSON structure with needed attribute values.

  • URL: /workbooks/{workbook-name}/executions
  • Status: 201
  • Returns: Created Execution
Request example
{
    "workbook_name": "my_deployment_workbook"
    "task": "deploy_env",
    "context": {
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
    }
}
Response example
{
    "id": "12304593450234",
    "workbook_name": "my_deployment_workbook"
    "target_task": "deploy_env"
    "state": "RUNNING"
}

Update an execution [PUT]

The only sensible field of an execution to updated is state. That way a user can manually suspend/resume the execution or completely stop it.

  • URL: /workbooks/{workbook-name}/executions/{execution-id}
  • Status: 200
  • Returns: Execution
Request example
{
    "id": "12304593450234",
    "state": "STOPPED"
}
Response example
{
    "id": "12304593450234",
    "workbook_name": "my_deployment_workbook",
    "task": "deploy_env",
    "context": {
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
    },
    "state": "STOPPED"
}

Task [/workbooks/{workbook_name}/executions/{execution_id}/tasks/{id}]

When a workflow starts Mistral creates an execution. It in turn consists of a set of tasks being processed within its scope. So Task is an instance of a task described in a Workbook that belongs to a particular execution.

A Task has the following attributes:

  • id
  • workbook_name
  • execution_id
  • name
  • description
  • action
  • state
  • tags


"state" can take one of the following values:

  • IDLE
  • RUNNING
  • SUCCESS
  • ERROR


"tags" is a list of values associated with a Task which can be used for grouping tasks using some criteria.

URL Parameters

  • workbook_name (string) - Workbook name.
  • execution_id (string) - Execution id.
  • id (string) - Task id.

Model

{
    "id": "12434234",
    "workbook_name": "my_deployment_workbook",
    "execution_id": "12304593450234",
    "name": "install_mc",
    "description": "Install Midnight Commander",
    "action": "install_mc",
    "state": "IDLE",
    "tags": ["deployment", "mc"]
}

Retrieve Task list [GET]

  • URL: /workbooks/{workbook-name}/executions/{execution-id}/tasks
  • Status: 200
  • Returns: Task list
Response example
{
    "tasks": [
        {
            "description": null,
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
            "id": "1a5b681c-2f9f-4634-8b4c-2306e4c17b75",
            "name": "createVM",
            "state": "ERROR",
            "tags": null,
            "workbook_name": "wb"
        },
        {
            "description": null,
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
            "id": "bd955236-04ea-4ee9-ab1f-3068ee72c2fa",
            "name": "sendCreateVMError",
            "state": "ERROR",
            "tags": null,
            "workbook_name": "wb"
        }
    ]
}

Retrieve a single task [GET]

  • URL: /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
  • Status: 200
  • Returns: Task

Update a task [PUT]

The only sensible field to update is "state". This way applications that handle task actions can communicate task states back to Mistral.

  • URL: /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
  • Status: 200
  • Returns: Task
Request example
{
    "id": "12434234",
    "state": "ERROR"
}