V2 API¶

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

Basics¶

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.

Workbooks¶

type Workbook¶

Workbook resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "definition": "HERE GOESWORKBOOK DEFINITION IN MISTRAL DSL v2",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "name": "book",
    "scope": "private",
    "tags": [
        "large",
        "expensive"
    ],
    "updated_at": "1970-01-01T00:00:00.000000"
}

definition¶

Type:	unicode

workbook definition in Mistral v2 DSL

scope¶

Type:	Enum(private, public)

‘private’ or ‘public’

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.

type Workbooks¶

A collection of Workbooks.

Data samples:

Json

{
    "workbooks": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "definition": "HERE GOESWORKBOOK DEFINITION IN MISTRAL DSL v2",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "name": "book",
            "scope": "private",
            "tags": [
                "large",
                "expensive"
            ],
            "updated_at": "1970-01-01T00:00:00.000000"
        }
    ]
}

GET /v2/workbooks¶

Return all workbooks.

Where project_id is the same as the requestor or project_id is different but the scope is public.

Return type:	`Workbooks`

GET /v2/workbooks¶

Return the named workbook. :type name: unicode

Return type:	`Workbook`

POST /v2/workbooks¶: Create a new workbook.

PUT /v2/workbooks¶: Update a workbook.

DELETE /v2/workbooks¶: Delete the named workbook. :type name: unicode

Workflows¶

type Workflow¶

Workflow resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "definition": "HERE GOESWORKFLOW DEFINITION IN MISTRAL DSL v2",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "input": "param1, param2",
    "name": "flow",
    "project_id": "a7eb669e9819420ea4bd1453e672c0a7",
    "scope": "private",
    "tags": [
        "large",
        "expensive"
    ],
    "updated_at": "1970-01-01T00:00:00.000000"
}

definition¶

Type:	unicode

Workflow definition in Mistral v2 DSL

scope¶

Type:	Enum(private, public)

‘private’ or ‘public’

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.

type Workflows¶

A collection of workflows.

Data samples:

Json

{
    "next": "http://localhost:8989/v2/workflows?sort_keys=id,name&sort_dirs=asc,desc&limit=10&marker=123e4567-e89b-12d3-a456-426655440000",
    "workflows": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "definition": "HERE GOESWORKFLOW DEFINITION IN MISTRAL DSL v2",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "input": "param1, param2",
            "name": "flow",
            "project_id": "a7eb669e9819420ea4bd1453e672c0a7",
            "scope": "private",
            "tags": [
                "large",
                "expensive"
            ],
            "updated_at": "1970-01-01T00:00:00.000000"
        }
    ]
}

GET /v2/workflows¶

Return a list of workflows.

Parameters:

marker – Optional. Pagination marker for large data sets.
limit – Optional. Maximum number of resources to return in a single result. Default value is None for backward compatibility.
sort_keys – Optional. Columns to sort results by. Default: created_at.
sort_dirs – Optional. Directions to sort corresponding to sort_keys, “asc” or “desc” can be choosed. Default: asc.
fields – Optional. A specified list of fields of the resource to be returned. ‘id’ will be included automatically in fields if it’s provided, since it will be used when constructing ‘next’ link.

Where project_id is the same as the requester or project_id is different but the scope is public. :type marker: uuid :type limit: int :type sort_keys: uniquelist :type sort_dirs: list :type fields: uniquelist

Return type:	`Workflows`

GET /v2/workflows¶

Return the named workflow. :type identifier: unicode

Return type:	`Workflow`

POST /v2/workflows¶

Create a new workflow.

NOTE: The text is allowed to have definitions: of multiple workflows. In this case they all will be created.

PUT /v2/workflows¶

Update one or more workflows.

Parameters:	identifier – Optional. If provided, it’s UUID of a workflow. Only one workflow can be updated with identifier param.

The text is allowed to have definitions of multiple workflows. In this case they all will be updated.

DELETE /v2/workflows¶: Delete a workflow. :type identifier: unicode

Actions¶

type Action¶

Action resource.

NOTE: 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.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "definition": "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "name": "flow",
    "scope": "private",
    "tags": [
        "large",
        "expensive"
    ],
    "updated_at": "1970-01-01T00:00:00.000000"
}

type Actions¶

A collection of Actions.

Data samples:

Json

{
    "actions": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "definition": "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "name": "flow",
            "scope": "private",
            "tags": [
                "large",
                "expensive"
            ],
            "updated_at": "1970-01-01T00:00:00.000000"
        }
    ],
    "next": "http://localhost:8989/v2/actions?sort_keys=id,name&sort_dirs=asc,desc&limit=10&marker=123e4567-e89b-12d3-a456-426655440000"
}

GET /v2/actions¶

Return all actions.

Parameters:	marker – Optional. Pagination marker for large data sets. limit – Optional. Maximum number of resources to return in a single result. Default value is None for backward compatibility. sort_keys – Optional. Columns to sort results by. Default: name. sort_dirs – Optional. Directions to sort corresponding to sort_keys, “asc” or “desc” can be choosed. Default: asc.

Where project_id is the same as the requester or project_id is different but the scope is public. :type marker: uuid :type limit: int :type sort_keys: uniquelist :type sort_dirs: list

Return type:	`Actions`

GET /v2/actions¶

Return the named action. :type name: unicode

Return type:	`Action`

POST /v2/actions¶

Create a new action.

NOTE: This text is allowed to have definitions: of multiple actions. In this case they all will be created.

PUT /v2/actions¶

Update one or more actions.

NOTE: This text is allowed to have definitions: of multiple actions. In this case they all will be updated.

DELETE /v2/actions¶: Delete the named action. :type name: unicode

Executions¶

type Execution¶

Execution resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "description": "this is the first execution.",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "input": "{}",
    "output": "{}",
    "params": "{\"env\": {\"k2\": 123, \"k1\": \"abc\"}}",
    "state": "SUCCESS",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
    "workflow_name": "flow"
}

description¶

Type:	unicode

description of workflow execution.

id¶

Type:	unicode

id is immutable and auto assigned.

input¶

Type:	json

input is a JSON structure containing workflow input values.

output¶

Type:	json

output is a workflow output.

params¶

Type:	json

params define workflow type specific parameters. For example, reverse workflow takes one parameter ‘task_name’ that defines a target task.

state¶

Type:	unicode

state can be one of: IDLE, RUNNING, SUCCESS, ERROR, PAUSED

state_info¶

Type:	unicode

an optional state information string

task_execution_id¶

Type:	unicode

reference to the parent task execution

workflow_id¶

Type:	unicode

reference to workflow ID

workflow_name¶

Type:	unicode

reference to workflow definition

type Executions¶

A collection of Execution resources.

Data samples:

Json

{
    "executions": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "description": "this is the first execution.",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "input": "{}",
            "output": "{}",
            "params": "{\"env\": {\"k2\": 123, \"k1\": \"abc\"}}",
            "state": "SUCCESS",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
            "workflow_name": "flow"
        }
    ],
    "next": "http://localhost:8989/v2/executions?sort_keys=id,workflow_name&sort_dirs=asc,desc&limit=10&marker=123e4567-e89b-12d3-a456-426655440000"
}

GET /v2/executions¶

Return all Executions.

Parameters:

marker (uuid) – Optional. Pagination marker for large data sets.
limit (int) – Optional. Maximum number of resources to return in a single result. Default value is None for backward compatibility.
sort_keys (uniquelist) – Optional. Columns to sort results by. Default: created_at, which is backward compatible.
sort_dirs (list) – Optional. Directions to sort corresponding to sort_keys, “asc” or “desc” can be chosen. Default: desc. The length of sort_dirs can be equal or less than that of sort_keys.

Return type:

Executions

GET /v2/executions¶

Return the specified Execution. :type id: unicode

Return type:	`Execution`

POST /v2/executions¶

Create a new Execution.

Parameters:	wf_ex (`Execution`) – Execution object with input content.
Return type:	`Execution`

PUT /v2/executions¶

Update the specified workflow execution.

Parameters:	id (`unicode`) – execution ID. wf_ex (`Execution`) – Execution object.
Return type:	`Execution`

DELETE /v2/executions¶: Delete the specified Execution. :type id: unicode

Tasks¶

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.

type Task¶

Task resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "name": "task",
    "processed": true,
    "published": "{\"key\": \"value\"}",
    "reset": true,
    "result": "task result",
    "state": "SUCCESS",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_execution_id": "123e4567-e89b-12d3-a456-426655440000",
    "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
    "workflow_name": "flow"
}

state¶

Type:	unicode

state can take one of the following values: IDLE, RUNNING, SUCCESS, ERROR, DELAYED

state_info¶

Type:	unicode

an optional state information string

type Tasks¶

A collection of tasks.

Data samples:

Json

{
    "tasks": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "name": "task",
            "processed": true,
            "published": "{\"key\": \"value\"}",
            "reset": true,
            "result": "task result",
            "state": "SUCCESS",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_execution_id": "123e4567-e89b-12d3-a456-426655440000",
            "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
            "workflow_name": "flow"
        }
    ]
}

GET /v2/tasks¶

Return all tasks within the execution.

Return type:	`Tasks`

GET /v2/tasks¶

Return the specified task. :type id: unicode

Return type:	`Task`

PUT /v2/tasks¶

Update the specified task execution.

Parameters:	id (`unicode`) – Task execution ID. task (`Task`) – Task execution object.
Return type:	`Task`

GET /v2/executions¶

Return all tasks within the workflow execution. :type workflow_execution_id: unicode

Return type:	`Tasks`

Action Executions¶

When a Task starts Mistral creates a set of Action Executions. So Action Execution is an instance of an action call described in a Workflow Task that belongs to a particular execution.

type ActionExecution¶

ActionExecution resource.

Data samples:

Json

{
    "accepted": true,
    "created_at": "1970-01-01T00:00:00.000000",
    "description": "My running action",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "input": "{\"first_name\": \"John\", \"last_name\": \"Doe\"}",
    "name": "std.echo",
    "output": "{\"some_output\": \"Hello, John Doe!\"}",
    "params": "{\"save_result\": true}",
    "state": "SUCCESS",
    "state_info": "SUCCESS",
    "tags": [
        "foo",
        "fee"
    ],
    "task_execution_id": "343e45623-e89b-12d3-a456-426655440090",
    "task_name": "task1",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_name": "flow"
}

type ActionExecutions¶

A collection of action_executions.

Data samples:

Json

{
    "action_executions": [
        {
            "accepted": true,
            "created_at": "1970-01-01T00:00:00.000000",
            "description": "My running action",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "input": "{\"first_name\": \"John\", \"last_name\": \"Doe\"}",
            "name": "std.echo",
            "output": "{\"some_output\": \"Hello, John Doe!\"}",
            "params": "{\"save_result\": true}",
            "state": "SUCCESS",
            "state_info": "SUCCESS",
            "tags": [
                "foo",
                "fee"
            ],
            "task_execution_id": "343e45623-e89b-12d3-a456-426655440090",
            "task_name": "task1",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_name": "flow"
        }
    ]
}

GET /v2/action_executions¶

Return all action_executions within the execution.

Return type:	`ActionExecutions`

GET /v2/action_executions¶

Return the specified action_execution. :type id: unicode

Return type:	`ActionExecution`

POST /v2/action_executions¶

Create new action_execution. :type action_ex: ActionExecution

Return type:	`ActionExecution`

PUT /v2/action_executions¶

Update the specified action_execution. :type id: unicode :type action_ex: ActionExecution

Return type:	`ActionExecution`

DELETE /v2/action_executions¶: Delete the specified action_execution. :type id: unicode

GET /v2/tasks¶

Return all action executions within the task execution. :type task_execution_id: unicode

Return type:	`ActionExecutions`

GET /v2/tasks¶

Return the specified action_execution. :type task_execution_id: unicode :type action_ex_id: unicode

Return type:	`ActionExecution`

Cron Triggers¶

Cron trigger is an object that allows to run Mistral workflows according to a time pattern (Unix crontab patterns format). Once a trigger is created it will run a specified workflow according to its properties: pattern, first_execution_time and remaining_executions.

type CronTrigger¶

CronTrigger resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "name": "my_trigger",
    "pattern": "* * * * *",
    "remaining_executions": 42,
    "scope": "private",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
    "workflow_input": "{}",
    "workflow_name": "my_wf",
    "workflow_params": "{}"
}

type CronTriggers¶

A collection of cron triggers.

Data samples:

Json

{
    "cron_triggers": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "name": "my_trigger",
            "pattern": "* * * * *",
            "remaining_executions": 42,
            "scope": "private",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_id": "123e4567-e89b-12d3-a456-426655441111",
            "workflow_input": "{}",
            "workflow_name": "my_wf",
            "workflow_params": "{}"
        }
    ]
}

GET /v2/cron_triggers¶

Return all cron triggers.

Return type:	`CronTriggers`

GET /v2/cron_triggers¶

Returns the named cron_trigger. :type name: unicode

Return type:	`CronTrigger`

POST /v2/cron_triggers¶

Creates a new cron trigger. :type cron_trigger: CronTrigger

Return type:	`CronTrigger`

DELETE /v2/cron_triggers¶: Delete cron trigger. :type name: unicode

Environments¶

Environment contains a set of variables which can be used in specific workflow. Using Environment possible to create and map action default values - just provide ‘__actions’ key in ‘variables’. All these variables can be accessed in workflow DSL by <% $.__env %> expression.

Example of using in DSL:

workflow:
  tasks:
    task1:
      action: std.echo output=<% $.__env.my_echo_output %>

Example of creating action defaults:

...ENV...
"variables": {
  "__actions": {
    "std.echo": {
      "output": "my_output"
    }
  }
},
...ENV...

Note: using CLI, Environment can be created via JSON or YAML file.

type Environment¶

Environment resource.

Data samples:

Json

{
    "created_at": "1970-01-01T00:00:00.000000",
    "description": "example environment entry",
    "id": "4d6d6583-e210-44a6-bc87-632f15f840b3",
    "name": "sample",
    "scope": "private",
    "updated_at": "1970-01-01T00:00:00.000000",
    "variables": "{\"database\": \"temp\", \"verbose\": true, \"timeout\": 600, \"server\": \"localhost\"}"
}

type Environments¶

A collection of Environment resources.

Data samples:

Json

{
    "environments": [
        {
            "created_at": "1970-01-01T00:00:00.000000",
            "description": "example environment entry",
            "id": "a712fbc5-8c94-4e44-94f0-01f19f7d1d14",
            "name": "sample",
            "scope": "private",
            "updated_at": "1970-01-01T00:00:00.000000",
            "variables": "{\"database\": \"temp\", \"verbose\": true, \"timeout\": 600, \"server\": \"localhost\"}"
        }
    ]
}

GET /v2/environments¶

Return all environments.

Where project_id is the same as the requestor or project_id is different but the scope is public.

Return type:	`Environments`

GET /v2/environments¶

Return the named environment. :type name: unicode

Return type:	`Environment`

POST /v2/environments¶

Create a new environment. :type env: Environment

Return type:	`Environment`

PUT /v2/environments¶

Update an environment. :type env: Environment

Return type:	`Environment`

DELETE /v2/environments¶: Delete the named environment. :type name: unicode

Services¶

Through service management API, system administrator or operator can retrieve Mistral services information of the system, including service group and service identifier. The internal implementation of this feature make use of tooz library, which needs coordinator backend(the most commonly used at present is Zookeeper) installed, please refer to tooz official documentation for more detailed instruction.

There are three service groups according to Mistral architecture currently, namely api_group, engine_group and executor_group. The service identifier contains name of the host the service is running on and the process identifier of the service on that host.

type Service¶

Service resource.

Data samples:

Json

{
    "name": "host1_1234",
    "type": "executor_group"
}

type Services¶

A collection of Services.

Data samples:

Json

{
    "services": [
        {
            "name": "host1_1234",
            "type": "executor_group"
        }
    ]
}

GET /v2/services¶

Return all services.

Return type:	`Services`

Validation¶

Validation endpoints allow to check correctness of workbook and workflow DSL without having to upload them into Mistral.

POST /v2/workbooks/validation: Validate workbook content (DSL grammar and semantics).
POST /v2/workflows/validation: Validate workflow content (DSL grammar and semantics).

These endpoints expect workbook or workflow text (DSL) correspondingly in a request body.

OpenStack

V2 API¶

Basics¶

Media Types¶

Error States¶

Application Root [/]¶

API v2 Root [/v2/]¶

Workbooks¶

Workflows¶

Actions¶

Executions¶

Tasks¶

Action Executions¶

Cron Triggers¶

Environments¶

Services¶

Validation¶

Table Of Contents

Previous topic

Next topic

Project Source

This Page

OpenStack

V2 API¶

Basics¶

Media Types¶

Error States¶

Application Root [/]¶

API v2 Root [/v2/]¶

Workbooks¶

Workflows¶

Actions¶

Executions¶

Tasks¶

Action Executions¶

Cron Triggers¶

Environments¶

Services¶

Validation¶

Table Of Contents

Previous topic

Next topic

Project Source

This Page

Quick search

Navigation