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" } ] }
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" } ] }
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" }
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.
-
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" }
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", "runtime_context": "{\"triggered_by\": [{\"event\": \"on-success\", \"task_id\": \"123-123-123\"}]}", "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_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", "runtime_context": "{\"triggered_by\": [{\"event\": \"on-success\", \"task_id\": \"123-123-123\"}]}", "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" } ] }
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, \"run_sync\": false}", "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, \"run_sync\": false}", "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" } ] }
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": "{}" } ] }
Environments¶
Environment contains a set of variables which can be used in specific workflow.
Using an Environment it is possible to create and map action default values -
just provide ‘__actions’ key in ‘variables’. All these variables can be
accessed using the Workflow Language with the <% $.__env %>
expression.
Example of usage:
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": "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\"}" }
-
type
Environments
¶ A collection of Environment resources.
Data samples:
- Json
{ "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\"}" } ] }
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" } ] }
Validation¶
Validation endpoints allow to check correctness of workbook, workflow and ad-hoc action Workflow Language without having to upload them into Mistral.
- POST /v2/workbooks/validation
- Validate workbook content (Workflow Language grammar and semantics).
- POST /v2/workflows/validation
- Validate workflow content (Workflow Language grammar and semantics).
- POST /v2/actions/validation
- Validate ad-hoc action content (Workflow Language grammar and semantics).
These endpoints expect workbook, workflow or ad-hoc action text (Workflow Language) correspondingly in a request body.