c07cf48a60
The writing styles at few places were not in compliance with the OpenStack writing style as mentioned in http://docs.openstack.org/contributor-guide/writing-style /general-writing-guidelines.html. This patch changes the heading styles and adds a few other minor changes in the documents. Change-Id: I0d90ba32ddcef0427b1dc4358206210f166e798a Partial-Implements: blueprint mistral-doc
238 lines
6.5 KiB
ReStructuredText
238 lines
6.5 KiB
ReStructuredText
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
|
|
---------
|
|
|
|
.. 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 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
|
|
|
|
.. code-block:: yaml
|
|
|
|
workflow:
|
|
tasks:
|
|
task1:
|
|
action: std.echo output=<% $.__env.my_echo_output %>
|
|
|
|
Example of creating action defaults
|
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
...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
|
|
|
|
|
|
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.
|
|
|
|
.. autotype:: mistral.api.controllers.v2.resources.Service
|
|
:members:
|
|
|
|
.. autotype:: mistral.api.controllers.v2.resources.Services
|
|
:members:
|
|
|
|
.. rest-controller:: mistral.api.controllers.v2.service:ServicesController
|
|
:webprefix: /v2/services
|
|
|
|
Validation
|
|
----------
|
|
|
|
Validation endpoints allow to check correctness of workbook, workflow and ad-hoc
|
|
action 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).
|
|
|
|
**POST /v2/actions/validation**
|
|
Validate ad-hoc action content (DSL grammar and semantics).
|
|
|
|
These endpoints expect workbook, workflow or ad-hoc action text (DSL) correspondingly
|
|
in a request body.
|