Jump to: navigation, search

Difference between revisions of "Mistral/RestAPIv2"

(Created page with "== Mistral API v1.0 == This API describes the ways of interacting with Mistral service via HTTP protocol using Representational State Transfer concept (ReST). === Media Type...")
 
 
(28 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Mistral API v1.0 ==
+
== This Wiki is no longer maintained ==
  
This API describes the ways of interacting with Mistral service via HTTP protocol using Representational
+
Please see the [https://docs.openstack.org/mistral/latest/api/index.html Mistral API documentation].
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|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|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'''
 
{
 
    "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"
 
}
 

Latest revision as of 12:40, 6 March 2018

This Wiki is no longer maintained

Please see the Mistral API documentation.