V2 API

Warning

(2014-10-5): 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.

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",
    "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
{
    "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",
            "scope": "private",
            "tags": [
                "large",
                "expensive"
            ],
            "updated_at": "1970-01-01T00:00:00.000000"
        }
    ]
}
GET /v2/workflows

Return all workflows.

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

Return type:Workflows
GET /v2/workflows

Return the named workflow. :type name: 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.

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

Delete the named workflow. :type name: 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"
        }
    ]
}
GET /v2/actions

Return all actions.

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

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",
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "input": "{}",
    "output": "{}",
    "params": "{\"env\": {\"k1\": \"abc\", \"k2\": 123}}",
    "state": "SUCCESS",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_name": "flow"
}
id
Type:unicode

id is immutable and auto assigned.

input
Type:unicode

input is a JSON structure containing workflow input values.

output
Type:unicode

output is a workflow output.

params
Type:unicode

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: RUNNING, SUCCESS, ERROR, PAUSED

state_info
Type:unicode

an optional state information string

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",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "input": "{}",
            "output": "{}",
            "params": "{\"env\": {\"k1\": \"abc\", \"k2\": 123}}",
            "state": "SUCCESS",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_name": "flow"
        }
    ]
}
GET /v2/executions

Return all Executions.

Return type:Executions
GET /v2/executions

Return the specified Execution. :type id: unicode

Return type:Execution
POST /v2/executions

Create a new Execution.

Parameters:
  • execution (Execution) – Execution object with input content.
Return type:

Execution

PUT /v2/executions

Update the specified Execution.

Parameters:
  • id (unicode) – execution ID.
  • execution (Execution) – Execution objects
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",
    "state": "SUCCESS",
    "updated_at": "1970-01-01T00:00:00.000000",
    "workflow_execution_id": "123e4567-e89b-12d3-a456-426655440000",
    "workflow_name": "flow"
}
state
Type:unicode

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

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",
            "state": "SUCCESS",
            "updated_at": "1970-01-01T00:00:00.000000",
            "workflow_execution_id": "123e4567-e89b-12d3-a456-426655440000",
            "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
GET /v2/executions

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

Return type:Tasks

Table Of Contents

Previous topic

REST API

Next topic

How to write an Action Plugin

This Page