REST API V2 =========== 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 --------- .. autotype:: mistral.api.controllers.v2.resources.Workbook :members: `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. .. autotype:: mistral.api.controllers.v2.resources.Workbooks :members: .. rest-controller:: mistral.api.controllers.v2.workbook:WorkbooksController :webprefix: /v2/workbooks Workflows --------- .. autotype:: mistral.api.controllers.v2.resources.Workflow :members: `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. .. autotype:: mistral.api.controllers.v2.resources.Workflows :members: .. rest-controller:: mistral.api.controllers.v2.workflow:WorkflowsController :webprefix: /v2/workflows Actions ------- .. autotype:: mistral.api.controllers.v2.resources.Action :members: .. autotype:: mistral.api.controllers.v2.resources.Actions :members: .. rest-controller:: mistral.api.controllers.v2.action:ActionsController :webprefix: /v2/actions Executions ---------- .. autotype:: mistral.api.controllers.v2.resources.Execution :members: .. autotype:: mistral.api.controllers.v2.resources.Executions :members: .. rest-controller:: mistral.api.controllers.v2.execution:ExecutionsController :webprefix: /v2/executions 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. .. autotype:: mistral.api.controllers.v2.resources.Task :members: .. autotype:: mistral.api.controllers.v2.resources.Tasks :members: .. rest-controller:: mistral.api.controllers.v2.task:TasksController :webprefix: /v2/tasks .. rest-controller:: mistral.api.controllers.v2.task:ExecutionTasksController :webprefix: /v2/executions 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. .. autotype:: mistral.api.controllers.v2.resources.ActionExecution :members: .. autotype:: mistral.api.controllers.v2.resources.ActionExecutions :members: .. rest-controller:: mistral.api.controllers.v2.action_execution:ActionExecutionsController :webprefix: /v2/action_executions .. rest-controller:: mistral.api.controllers.v2.action_execution:TasksActionExecutionController :webprefix: /v2/tasks 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. .. autotype:: mistral.api.controllers.v2.resources.CronTrigger :members: .. autotype:: mistral.api.controllers.v2.resources.CronTriggers :members: .. rest-controller:: mistral.api.controllers.v2.cron_trigger:CronTriggersController :webprefix: /v2/cron_triggers 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: .. code-block:: yaml 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. .. autotype:: mistral.api.controllers.v2.resources.Environment :members: .. autotype:: mistral.api.controllers.v2.resources.Environments :members: .. rest-controller:: mistral.api.controllers.v2.environment:EnvironmentController :webprefix: /v2/environments 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. Code Sources ------------ Code source is a type of entity that holds information about an executable module. Mostly, it was designed to represent as a Python module and this is its main use at the moment. However, it can also be used for other languages in future. Code sources are now used as part of the dynamic actions mechanism. The normal flow is to first upload a code source, i.e. a regular Python file, and then create one or more dynamic actions using **POST /v2/dynamic-actions** and specifying the name of the action, its class name as it's declared in the source code, and the reference to the source code itself. .. autotype:: mistral.api.controllers.v2.resources.CodeSource :members: .. autotype:: mistral.api.controllers.v2.resources.CodeSources :members: .. rest-controller:: mistral.api.controllers.v2.code_source:CodeSourcesController :webprefix: /v2/code-sources Dynamic Actions --------------- Dynamic action is the type of action that can be created right through the API, without having to reboot Mistral like in other cases. Before adding a dynamic action, a client first needs to upload a code source (i.e. a Python module) that contains the corresponding Python class that implements the action, and then create the action using the method **POST /v2/dynamic-actions** where the name of the action, its class name as it's declared in the code source code, and the reference to the source code itself must be specified. .. autotype:: mistral.api.controllers.v2.resources.DynamicAction :members: .. autotype:: mistral.api.controllers.v2.resources.DynamicActions :members: .. rest-controller:: mistral.api.controllers.v2.dynamic_action:DynamicActionsController :webprefix: /v2/dynamic-actions