Jump to: navigation, search

Difference between revisions of "Mistral/RestAPIv2"

(Action Execution [/action_executions/{action-execution-id}])
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Mistral API v2 ==
+
== This Wiki is no longer maintained ==
  
'''NOTE''': API described in this document might slightly change within a short period of time (2-3 weeks) and should be now considered '''experimental'''. Mistral team is now actively working on stabilization.
+
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.
 
 
 
=== API v2 Root [/v2/] ===
 
 
 
All API v2 urls are relative to API v2 root.
 
 
 
=== Workbook [/workbooks/{name}] ===
 
 
 
See what [[Mistral/DSLv2#Workbooks|Workbooks]] are in Mistral DSL v2 Specification.
 
 
 
A Workbook has the following attributes:
 
 
 
* id
 
* name
 
* tags
 
* definition
 
* created_at
 
* updated_at
 
 
 
'''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.). Note that '''name''' and '''tags''' get inferred from workbook definition when Mistral service receives a POST request. So they can't be changed in another way.
 
 
 
==== URL Parameters ====
 
 
 
* name - Workbook name.
 
 
 
==== Model ====
 
 
 
{
 
    "name" : "my_deployment_workbook",
 
    "tags": ["deployment", "mc"],
 
    "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Retrieve Workbook list [GET] ====
 
* '''URL:''' /workbooks
 
* '''Status:''' 200
 
* '''Returns:''' List of workbooks
 
 
 
'''Response'''
 
{
 
    "workbooks": [
 
        {
 
            "name" : "my_deployment_workbook",
 
            "tags": ["deployment", "mc"],
 
            "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
 
            "created_at" : "2014-09-25 03:35:36",
 
            "updated_at" : "2014-09-25 03:35:36",
 
        }
 
    ]
 
}
 
 
 
==== Retrieve a single Workbook [GET] ====
 
* '''URL:''' /workbooks/{workbook_name}
 
* '''Status:''' 200
 
* '''Returns:''' Workbook
 
 
 
'''Response'''
 
{
 
    "name" : "my_deployment_workbook",
 
    "tags": ["deployment", "mc"],
 
    "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Create a Workbook [POST] ====
 
To create a new Workbook simply provide a YAML structure containing workbook definition as a string value.
 
 
 
* '''URL:''' /workbooks
 
* '''Status:''' 201
 
* '''Returns:''' Created Workbook
 
 
 
'''Request (text/plain)'''
 
 
    <HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
 
 
 
Example:
 
 
 
'''Request (text/plain)'''
 
    ---
 
    version: 2.0
 
    workflows:
 
        tasks:
 
            task1:
 
                action: std.echo output="Hello world!"
 
 
 
==== Update a Workbook [PUT] ====
 
To modify a workbook simply send a YAML structure containing workbook definition as a string value.
 
 
 
* '''URL:''' /workbooks
 
* '''Status:''' 200
 
* '''Returns:''' Updated Workbook
 
 
 
'''Request example'''
 
 
 
    <HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
 
 
 
==== Validate a Workbook [POST] ====
 
To modify a workbook simply send a YAML structure containing workbook definition as a string value.
 
 
 
* '''URL:''' /workbooks/validate
 
* '''Status:''' 200
 
* '''Returns:''' JSON containing 'valid' boolean key meaning whether valid given workbook or not.
 
 
 
'''Request example'''
 
 
 
    <HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
 
 
 
'''Response example'''
 
{
 
    "valid": true
 
}
 
 
 
==== Delete a Workbook [DELETE] ====
 
 
 
* '''URL:''' /workbooks/{workbook_name}
 
* '''Status:''' 204
 
* '''Returns:''' No content
 
 
 
=== Workflow [/workflows/{name}] ===
 
 
 
See what [[Mistral/DSLv2#Workflows|Workflows]] are in Mistral DSL v2 Specification.
 
 
 
A Workflow has the following attributes:
 
 
 
* id
 
* name
 
* tags
 
* definition
 
* created_at
 
* updated_at
 
 
 
'''name''' is immutable. '''tags''' is a list of values associated with a workflow that a user can use to group workflows by some criteria. Note that '''name''' and '''tags''' get inferred from workflow definition when Mistral service receives a POST request. So they can't be changed in another way.
 
 
 
==== URL Parameters ====
 
 
 
* name - Workflow name.
 
 
 
==== Model ====
 
 
 
{
 
    "name" : "my_workflow",
 
    "tags": ["deployment", "mc"],
 
    "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Retrieve Workflow list [GET] ====
 
* '''URL:''' /workflows
 
* '''Status:''' 200
 
* '''Returns:''' List of Workflows
 
 
 
'''Response'''
 
{
 
    "workflows": [
 
        {
 
            "name" : "my_workflow",
 
            "tags": ["deployment"],
 
            "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
 
            "created_at" : "2014-09-25 03:35:36",
 
            "updated_at" : "2014-09-25 03:35:36",
 
        }
 
    ]
 
}
 
 
 
==== Retrieve a single Workflow [GET] ====
 
* '''URL:''' /workflows/{workflows_name}
 
* '''Status:''' 200
 
* '''Returns:''' Workflow
 
 
 
'''Response'''
 
{
 
    "name" : "my_workflow",
 
    "tags": ["deployment"],
 
    "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Create a Workflow(s) [POST] ====
 
To create a new Workflow simply provide a YAML structure containing workflow definition as a string value.
 
 
 
* '''URL:''' /workflows
 
* '''Status:''' 201
 
* '''Returns:''' List of created Workflows
 
 
 
'''Request (text/plain)'''
 
 
    <HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
 
 
 
'''Request example (text/plain)'''
 
 
 
---
 
version: 2.0
 
my_workflow:
 
  tasks
 
    task1:
 
      action: std.echo output="Hello World!"
 
 
 
==== Update a Workflow(s) [PUT] ====
 
To modify a workflow simply send a YAML structure containing workflow definition as a string value.
 
 
 
* '''URL:''' /workflows
 
* '''Status:''' 200
 
* '''Returns:''' List of Updated Workflows
 
 
 
'''Request example (text/plain)'''
 
 
 
    <HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
 
 
 
 
 
==== Validate a Workflow [POST] ====
 
To modify a workbook simply send a YAML structure containing workflow definition as a string value.
 
 
 
* '''URL:''' /workflows/validate
 
* '''Status:''' 200
 
* '''Returns:''' JSON containing 'valid' boolean key meaning whether valid given workbook or not.
 
 
 
'''Request example'''
 
 
 
    <HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
 
 
 
'''Response example'''
 
{
 
    "valid": true
 
}
 
==== Delete a Workflow [DELETE] ====
 
 
 
* '''URL:''' /workflow/{workflow_name}
 
* '''Status:''' 204
 
* '''Returns:''' No content
 
 
 
=== Action [/actions/{name}] ===
 
 
 
See what [[Mistral/DSLv2#Actions|Actions]] are in Mistral DSL v2 Specification.
 
 
 
Action has the following attributes:
 
 
 
* id
 
* name
 
* description
 
* definition
 
* created_at
 
* updated_at
 
 
 
'''name''' is immutable. Note that '''name''' and '''description''' get inferred from action definition when Mistral service receives a POST request. So they can't be changed in another way.
 
 
 
==== URL Parameters ====
 
 
 
* name - Action name.
 
 
 
==== Model ====
 
 
 
{
 
    "name" : "my_action",
 
    "description": "My cool action",
 
    "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Retrieve Action list [GET] ====
 
* '''URL:''' /action
 
* '''Status:''' 200
 
* '''Returns:''' List of Actions
 
 
 
'''Response'''
 
{
 
    "actions": [
 
        {
 
            "name" : "my_action",
 
            "description": "My custom ad-hoc action",
 
            "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2",
 
            "created_at" : "2014-09-25 03:35:36",
 
            "updated_at" : "2014-09-25 03:35:36",
 
        }
 
    ]
 
}
 
 
 
==== Retrieve a single Action [GET] ====
 
* '''URL:''' /actions/{action_name}
 
* '''Status:''' 200
 
* '''Returns:''' Action
 
 
 
'''Response'''
 
{
 
    "name" : "my_action",
 
    "description": "My ad-hoc action",
 
    "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2",
 
    "created_at" : "2014-09-25 03:35:36",
 
    "updated_at" : "2014-09-25 03:35:36",
 
}
 
 
 
==== Create a Action(s) [POST] ====
 
To create a new Action simply provide a JSON structure containing attribute 'definition' and its value.
 
 
 
* '''URL:''' /actions
 
* '''Status:''' 201
 
* '''Returns:''' List of created Actions
 
 
 
'''Request (application/json)'''
 
{
 
    "definition" : "HERE GOES ONE ORE MORE ACTION DEFINITIONS IN MISTRAL DSL v2",
 
}
 
 
 
==== Update a Action(s) [PUT] ====
 
To modify an Action simply send a JSON structure containing attribute 'definition' and its value.
 
 
 
* '''URL:''' /actions
 
* '''Status:''' 200
 
* '''Returns:''' List of updated Actions
 
 
 
'''Request example'''
 
{
 
    "definition" : "HERE GOES ONE ORE MORE ACTION DEFINITIONS IN MISTRAL DSL v2",
 
}
 
 
 
==== Delete a Action [DELETE] ====
 
 
 
* '''URL:''' /action/{action_name}
 
* '''Status:''' 204
 
* '''Returns:''' No content
 
 
 
=== Execution [/executions/{id}] ===
 
A particular workflow execution.
 
 
 
An Execution has the following attributes:
 
 
 
* id
 
* workflow_name
 
* params
 
* input
 
* output
 
* state
 
* created_at
 
* updated_at
 
 
 
Note that '''id''' is immutable and automatically assigned by Mistral at creation time. '''params''' define workflow type specific parameters. For example, [[mistral/DSLv2#Reverse_Workflow|reverse workflow]] takes one parameter 'task_name' that defines a target task. '''input''' is a JSON structure containing workflow input values. '''output''' is a workflow output. '''state''' can take one of the following values:
 
 
 
* RUNNING
 
* SUCCESS
 
* ERROR
 
* PAUSED
 
 
 
==== URL Parameters ====
 
* id (string) - Execution id.
 
 
 
==== Model ====
 
{
 
    "id": "12304593450234",
 
    "workflow_name": "my_workflow",
 
    "params": {},
 
    "input": {
 
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 
    },
 
    "output": {
 
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 
    },
 
    "state": "RUNNING",
 
    "created_at": "2014-09-25 03:35:36",
 
    "updated_at": "2014-09-25 03:35:36"
 
}
 
 
 
==== Retrieve Execution list [GET] ====
 
 
 
* '''URL:''' /executions
 
* '''Status:''' 200
 
* '''Returns:''' List of Executions
 
 
 
==== Retrieve a single execution [GET] ====
 
 
 
* '''URL:''' /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:''' /executions
 
* '''Status:''' 201
 
* '''Returns:''' Created Execution
 
 
 
'''Request example'''
 
{
 
    "workflow_name": "my_workflow"
 
    "input": {
 
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 
    }
 
}
 
 
 
'''Response example'''
 
{
 
    "id": "12304593450234",
 
    "workflow_name": "my_workflow"
 
    "params": {},
 
    "input": {
 
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 
    },
 
    "output": {},
 
    "state": "RUNNING",
 
    "created_at": "2014-09-25 03:35:36",
 
    "updated_at": "2014-09-25 03:35:36"
 
}
 
 
 
==== 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.
 
 
 
* '''URL:''' /executions/{execution-id}
 
* '''Status:''' 200
 
* '''Returns:''' Execution
 
 
 
'''Request example'''
 
{
 
    "state": "PAUSED"
 
}
 
 
 
'''Response example'''
 
{
 
    "id": "12304593450234",
 
    "workflow_name": "my_workflow"
 
    "params": {},
 
    "input": {
 
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 
    },
 
    "output": {},
 
    "state": "PAUSED",
 
    "created_at": "2014-09-25 03:35:36",
 
    "updated_at": "2014-09-25 03:35:36"
 
}
 
 
 
=== Task [/tasks/{id}] ===
 
When a workflow starts Mistral creates an execution. It in turn consists of a set of tasks. So Task is an instance of a task described in a Workflow that belongs to a particular execution.
 
 
 
A Task has the following attributes:
 
 
 
* id
 
* name
 
* workflow_name
 
* workflow_execution_id
 
* result
 
* published
 
* created_at
 
* updated_at
 
 
 
"'''state'''" can take one of the following values:
 
 
 
* IDLE
 
* RUNNING
 
* SUCCESS
 
* ERROR
 
* DELAYED
 
 
 
==== URL Parameters ====
 
* id (string) - Task id.
 
 
 
==== Model ====
 
{
 
    "id": "12434234",
 
    "name": "create_vm",
 
    "workflow_name": "my_workflow",
 
    "execution_id": "12304593450234",
 
    "input": {
 
        "image_id": "1-2-3-4"
 
    },
 
    "state": "RUNNING",
 
    "created_at": "2014-09-25 03:35:36",
 
    "updated_at": "2014-09-25 03:35:36"
 
}
 
 
 
==== Retrieve Task list [GET] ====
 
 
 
* '''URL:''' /tasks
 
* '''Status:''' 200
 
* '''Returns:''' Task list
 
 
 
'''Response example'''
 
{
 
    "tasks": [
 
        {
 
            "id": "12434234",
 
            "name": "create_vm",
 
            "workflow_name": "my_workflow",
 
            "execution_id": "12304593450234",
 
            "input": {
 
                "image_id": "1-2-3-4"
 
            },
 
            "state": "SUCCESS",
 
            "created_at": "2014-09-25 03:35:36",
 
            "updated_at": "2014-09-25 03:35:36"
 
        },
 
        {
 
            "id": "12434235",
 
            "name": "associate_ip",
 
            "workflow_name": "my_workflow",
 
            "execution_id": "12304593450234",
 
            "input": {
 
                "vm_id": "1-2-3-4"
 
            },
 
            "state": "RUNNING",
 
            "created_at": "2014-09-25 03:35:36",
 
            "updated_at": "2014-09-25 03:35:36"
 
        },
 
    ]
 
}
 
 
 
==== Retrieve a single task [GET] ====
 
 
 
* '''URL:''' /tasks/{task-id}
 
* '''Status:''' 200
 
* '''Returns:''' Task
 
 
 
==== Retrieve Action Execution list related to specific Task [GET] ====
 
 
 
* '''URL:''' /tasks/{task-id}/action_executions
 
* '''Status:''' 200
 
* '''Returns:''' Action Execution list
 
 
 
 
 
=== Action Execution [/tasks/{id}] ===
 
When a Task starts Mistral creates a set of Action Executions. So Action Execution is an instance of a action call described in a Workflow Task that belongs to a particular execution.
 
 
 
An Action Execution has the following attributes:
 
 
 
* id
 
* name
 
* workflow_name
 
* task_name
 
* task_execution_id
 
* state
 
* accepted
 
* input
 
* output
 
* created_at
 
* updated_at
 
 
 
"'''state'''" can take one of the following values:
 
 
 
* IDLE
 
* RUNNING
 
* SUCCESS
 
* ERROR
 
* DELAYED
 
 
 
==== URL Parameters ====
 
* id (string) - Action Execution id.
 
 
 
==== Model ====
 
{
 
    "id": '123e4567-e89b-12d3-a456-426655440000',
 
    "workflow_name": "flow",
 
    "task_name": "task1",
 
    "workflow_execution_id": "653e4127-e89b-12d3-a456-426655440076",
 
    "task_execution_id": "343e45623-e89b-12d3-a456-426655440090",
 
    "state": "SUCCESS",
 
    "state_info": "SUCCESS",
 
    "tags": ['foo', 'fee'],
 
    "definition_name": "std.echo,
 
    "accepted": true,
 
    "input": {"first_name": "John", "last_name": "Doe"},
 
    "output": "{"some_output": "Hello, John Doe!"},
 
    "created_at": "1970-01-01T00:00:00.000000",
 
    "updated_at": "1970-01-01T00:00:00.000000"
 
}
 
 
 
==== Retrieve Action Execution list [GET] ====
 
 
 
* '''URL:''' /action_executions
 
* '''Status:''' 200
 
* '''Returns:''' Action Execution list
 
 
 
'''Response example'''
 
{
 
    "action_executions": [
 
        {
 
            "accepted": true,
 
            "created_at": "2015-05-06 09:17:39",
 
            "id": "0962a4e6-4e5a-4729-b758-198aa43d5bf6",
 
            "input": "{\"output\": 2}",
 
            "name": "std.echo",
 
            "output": "{\"result\": 2}",
 
            "state": "SUCCESS",
 
            "task_execution_id": "0e8dee21-a291-4b1e-be25-8dfe12d92264",
 
            "task_name": "echo",
 
            "updated_at": "2015-05-06 09:17:41",
 
            "workflow_name": "wf_work"
 
        },
 
        {
 
            "accepted": true,
 
            "created_at": "2015-05-06 09:17:39",
 
            "id": "7915963b-02ec-41c1-bbd7-7eb88bf23845",
 
            "input": "{\"output\": 3}",
 
            "name": "std.echo",
 
            "output": "{\"result\": 3}",
 
            "state": "SUCCESS",
 
            "task_execution_id": "9e9722bf-116f-4704-913a-70031e3cebf6",
 
            "task_name": "echo",
 
            "updated_at": "2015-05-06 09:17:40",
 
            "workflow_name": "wf_work"
 
        }
 
    ]
 
}
 
 
 
==== Retrieve a single action execution [GET] ====
 
 
 
* '''URL:''' /action_executions/{action-execution-id}
 
* '''Status:''' 200
 
* '''Returns:''' Action Execution
 
 
 
==== Update an Action Execution [PUT] ====
 
The only two sensible fields to update are '''"state"''' and '''"output"'''. When using asynchronous processing they can be used to notify Mistral with action execution state and output.
 
 
 
* '''URL:''' /action_executions/{action-execution-id}
 
* '''Status:''' 200
 
* '''Returns:''' Action Execution
 
 
 
'''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.