This API describes the ways of interacting with Mistral service via HTTP protocol using Representational State Transfer concept (ReST).
Currently this API relies on JSON to represent states of REST resources.
The common HTTP Response Status Codes (https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.
Application Root provides links to all possible API methods for Mistral. URLs for other resources described below are relative to Application Root.
All API v2 urls are relative to API v2 root.
Workbook resource.
Data samples:
{
"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"
}
| Type: | unicode |
|---|
workbook definition in Mistral v2 DSL
| 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.
A collection of Workbooks.
Data samples:
{
"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"
}
]
}
Return a list of workbooks.
| Parameters: |
|
|---|
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 :type created_at: unicode :type definition: unicode :type name: unicode :type scope: Enum(private, public) :type tags: unicode :type updated_at: unicode
| Return type: | Workbooks |
|---|
Create a new workbook.
Update a workbook.
Delete the named workbook. :type name: unicode
Workflow resource.
Data samples:
{
"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"
}
| Type: | unicode |
|---|
Workflow definition in Mistral v2 DSL
| 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.
A collection of workflows.
Data samples:
{
"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"
}
]
}
Return a list of workflows.
| Parameters: |
|
|---|---|
| Return type: |
Create a new workflow.
Update one or more workflows.
| Parameters: |
|
|---|
The text is allowed to have definitions of multiple workflows. In this case they all will be updated.
Delete a workflow. :type identifier: unicode
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:
{
"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"
}
A collection of Actions.
Data samples:
{
"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"
}
Return all actions.
| Parameters: |
|
|---|
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 :type created_at: unicode :type name: unicode :type scope: Enum(private, public) :type tags: unicode :type updated_at: unicode :type description: unicode :type definition: unicode :type is_system: unicode :type input: unicode
| Return type: | Actions |
|---|
Return the named action.
| Parameters: |
|
|---|---|
| Return type: |
Create a new action.
Update one or more actions.
Delete the named action. :type identifier: unicode
Execution resource.
Data samples:
{
"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"
}
| Type: | unicode |
|---|
description of workflow execution.
| Type: | unicode |
|---|
id is immutable and auto assigned.
| Type: | json |
|---|
input is a JSON structure containing workflow input values.
| Type: | json |
|---|
output is a workflow output.
| Type: | json |
|---|
params define workflow type specific parameters. For example, reverse workflow takes one parameter ‘task_name’ that defines a target task.
| Type: | unicode |
|---|
state can be one of: IDLE, RUNNING, SUCCESS, ERROR, PAUSED
| Type: | unicode |
|---|
an optional state information string
| Type: | unicode |
|---|
reference to the parent task execution
| Type: | unicode |
|---|
reference to workflow ID
| Type: | unicode |
|---|
reference to workflow definition
A collection of Execution resources.
Data samples:
{
"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"
}
Return all Executions.
| Parameters: |
|
|---|---|
| Return type: |
Create a new Execution.
| Parameters: |
|
|---|---|
| Return type: |
Update the specified workflow execution.
| Parameters: |
|
|---|---|
| Return type: |
Delete the specified Execution. :type id: unicode
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.
Task resource.
Data samples:
{
"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"
}
| Type: | unicode |
|---|
state can take one of the following values: IDLE, RUNNING, SUCCESS, ERROR, DELAYED
| Type: | unicode |
|---|
an optional state information string
A collection of tasks.
Data samples:
{
"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"
}
]
}
Return all tasks.
Where project_id is the same as the requester or project_id is different but the scope is public.
| Parameters: |
|
|---|---|
| Return type: |
Update the specified task execution.
| Parameters: |
|
|---|---|
| Return type: |
Return all tasks within the execution.
Where project_id is the same as the requester or project_id is different but the scope is public.
| Parameters: |
|
|---|---|
| Return type: |
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.
ActionExecution resource.
Data samples:
{
"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"
}
A collection of action_executions.
Data samples:
{
"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"
}
]
}
Return all tasks within the execution.
Where project_id is the same as the requester or project_id is different but the scope is public.
| Parameters: |
|
|---|---|
| Return type: |
Return the specified action_execution. :type id: unicode
| Return type: | ActionExecution |
|---|
Create new action_execution. :type action_ex: ActionExecution
| Return type: | ActionExecution |
|---|
Update the specified action_execution. :type id: unicode :type action_ex: ActionExecution
| Return type: | ActionExecution |
|---|
Delete the specified action_execution. :type id: unicode
Return all tasks within the execution.
Where project_id is the same as the requester or project_id is different but the scope is public.
| Parameters: |
|
|---|---|
| Return type: |
Return the specified action_execution. :type task_execution_id: unicode :type action_ex_id: unicode
| Return type: | ActionExecution |
|---|
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.
CronTrigger resource.
Data samples:
{
"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": "{}"
}
A collection of cron triggers.
Data samples:
{
"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": "{}"
}
]
}
Return all cron triggers.
| Parameters: |
|
|---|---|
| Return type: |
Returns the named cron_trigger. :type name: unicode
| Return type: | CronTrigger |
|---|
Creates a new cron trigger.
| Parameters: |
|
|---|---|
| Return type: |
Delete cron trigger. :type name: unicode
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.
Environment resource.
Data samples:
{
"created_at": "1970-01-01T00:00:00.000000",
"description": "example environment entry",
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "sample",
"scope": "private",
"updated_at": "1970-01-01T00:00:00.000000",
"variables": "{\"database\": \"temp\", \"verbose\": true, \"timeout\": 600, \"server\": \"localhost\"}"
}
A collection of Environment resources.
Data samples:
{
"environments": [
{
"created_at": "1970-01-01T00:00:00.000000",
"description": "example environment entry",
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "sample",
"scope": "private",
"updated_at": "1970-01-01T00:00:00.000000",
"variables": "{\"database\": \"temp\", \"verbose\": true, \"timeout\": 600, \"server\": \"localhost\"}"
}
]
}
Return all environments.
Where project_id is the same as the requester or project_id is different but the scope is public.
| Parameters: |
|
|---|---|
| Return type: |
Return the named environment. :type name: unicode
| Return type: | Environment |
|---|
Create a new environment. :type env: Environment
| Return type: | Environment |
|---|
Update an environment. :type env: Environment
| Return type: | Environment |
|---|
Delete the named environment. :type name: unicode
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.
Service resource.
Data samples:
{
"name": "host1_1234",
"type": "executor_group"
}
A collection of Services.
Data samples:
{
"services": [
{
"name": "host1_1234",
"type": "executor_group"
}
]
}
Validation endpoints allow to check correctness of workbook, workflow and ad-hoc action DSL without having to upload them into Mistral.
These endpoints expect workbook, workflow or ad-hoc action text (DSL) correspondingly in a request body.