Jump to: navigation, search

Difference between revisions of "Mistral/RestAPIv2"

(Workbook Definition [/workbook/{workbook_name}/definition])
 
(26 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Mistral API v2.0 ==
+
== This Wiki is no longer maintained ==
  
'''TODO'''
+
Please see the [https://docs.openstack.org/mistral/latest/api/index.html Mistral API documentation].
 
 
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 states of REST resources.
 
 
 
=== 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
 
 
 
=== 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.