|
|
(26 intermediate revisions by 2 users not shown) |
Line 1: |
Line 1: |
− | == Mistral API v2.0 == | + | == This Wiki is no longer maintained == |
| | | |
− | '''TODO'''
| + | Please see the [https://docs.openstack.org/mistral/latest/api/index.html Mistral API documentation]. |
− | | |
− | This API describes the ways of interacting with Mistral service via HTTP protocol using Representational State Transfer concept (ReST).
| |
− | | |
− | === 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.
| |
− | | |
− | === Workbook [/workbooks/{name}] ===
| |
− | Workbook describes tasks, dependencies and transitions between them, actions, triggers and other entities related to some particular business field. In other words, this is a definition of how tasks should be processed in a particular case and a set of rules describing how and when to run them. See [[Mistral/DSL|Mistral DSL Specification]] for details.
| |
− | | |
− | A Workbook has the following attributes:
| |
− | | |
− | * name
| |
− | * description
| |
− | * tags
| |
− | | |
− | | |
− | Note that '''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.)
| |
− | | |
− | ==== URL Parameters ====
| |
− | * name - Workbook name.
| |
− | | |
− | ==== Model ====
| |
− | | |
− | {
| |
− | "name" : "my_deployment_workbook",
| |
− | "description" : "A set of tasks for deployment",
| |
− | "tags": ["deployment", "mc"]
| |
− | }
| |
− | | |
− | ==== Retrieve Workbook list [GET] ====
| |
− | * '''URL:''' /workbooks
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' List of workbooks
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "workbooks": [
| |
− | {
| |
− | "name": "my_deployment_workbook",
| |
− | "description": "My deployment workbook",
| |
− | "tags": ["deployment", "mc"]
| |
− | }
| |
− | ]
| |
− | }
| |
− | | |
− | ==== Retrieve a single Workbook [GET] ====
| |
− | * '''URL:''' /workbooks/{workbook_name}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Workbook
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "name": "my_deployment_workbook",
| |
− | "description": "My deployment workbook",
| |
− | "tags": ["deployment", "mc"]
| |
− | }
| |
− | | |
− | ==== Create a Workbook [POST] ====
| |
− | To create a new Workbook simply provide a JSON structure containing attribute values.
| |
− | | |
− | * '''URL:''' /workbooks
| |
− | * '''Status:''' 201
| |
− | * '''Returns:''' Created Workbook
| |
− | | |
− | '''Request (application/json)'''
| |
− | {
| |
− | "name": "my_deployment_workbook",
| |
− | "description": "My deployment workbook",
| |
− | "tags": ["deployment", "mc"]
| |
− | }
| |
− | | |
− | ==== Update a Workbook [PUT] ====
| |
− | To modify a workbook simply send a JSON structure containing values for corresponding mutable fields.
| |
− | | |
− | * '''URL:''' /workbook/{workbook_name}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Updated Workbook
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "name": "my_deployment_workbook",
| |
− | "description": "My cool deployment workbook!",
| |
− | "tags": ["deployment", "mc", "new_tag"]
| |
− | }
| |
− | | |
− | ==== Delete a Workbook [DELETE] ====
| |
− | | |
− | * '''URL:''' /workbook/{workbook_name}
| |
− | * '''Status:''' 204
| |
− | * '''Returns:''' No content
| |
− | | |
− | === Execution [/workbooks/{workbook_name}/executions/{id}] ===
| |
− | A particular workflow execution.
| |
− | | |
− | An Execution has the following attributes:
| |
− | | |
− | * id
| |
− | * workbook_name
| |
− | * task
| |
− | * context
| |
− | * state
| |
− | | |
− | | |
− | Note that '''id''' is immutable and automatically assigned by Mistral at creation time. '''task''' defines a task that the workflow should start with. '''context''' is a JSON structure containing workflow input values. '''state''' can take one of the following values:
| |
− | | |
− | * IDLE
| |
− | * RUNNING
| |
− | * SUCCESS
| |
− | * ERROR
| |
− | * STOPPED
| |
− | * DELAYED
| |
− | | |
− | ==== URL Parameters ====
| |
− | * workbook_name (string) - Workbook name.
| |
− | * id (string) - Execution id.
| |
− | | |
− | ==== Model ====
| |
− | {
| |
− | "id": "12304593450234",
| |
− | "workbook_name": "my_deployment_workbook",
| |
− | "task": "deploy_env",
| |
− | "context": {
| |
− | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
− | },
| |
− | "state": "RUNNING"
| |
− | }
| |
− | | |
− | ==== Retrieve Execution list [GET] ====
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' List of Executions
| |
− | | |
− | ==== Retrieve a single execution [GET] ====
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Execution
| |
− | | |
− | ==== Create an execution [POST] ====
| |
− | To create a new execution simply provide a JSON structure with needed attribute values.
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions
| |
− | * '''Status:''' 201
| |
− | * '''Returns:''' Created Execution
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "workbook_name": "my_deployment_workbook"
| |
− | "task": "deploy_env",
| |
− | "context": {
| |
− | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
− | }
| |
− | }
| |
− | | |
− | '''Response example'''
| |
− | {
| |
− | "id": "12304593450234",
| |
− | "workbook_name": "my_deployment_workbook"
| |
− | "target_task": "deploy_env"
| |
− | "state": "RUNNING"
| |
− | }
| |
− | | |
− | ==== Update an execution [PUT] ====
| |
− | The only sensible field of an execution to updated is '''state'''. That way a user can manually suspend/resume the execution or completely stop it.
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Execution
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "state": "STOPPED"
| |
− | }
| |
− | | |
− | '''Response example'''
| |
− | {
| |
− | "id": "12304593450234",
| |
− | "workbook_name": "my_deployment_workbook",
| |
− | "task": "deploy_env",
| |
− | "context": {
| |
− | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
− | },
| |
− | "state": "STOPPED"
| |
− | }
| |
− | | |
− | === Task [/workbooks/{workbook_name}/executions/{execution_id}/tasks/{id}] ===
| |
− | When a workflow starts Mistral creates an execution. It in turn consists of a set of tasks being processed within its scope. So Task is an instance of a task described in a Workbook that belongs to a particular execution.
| |
− | | |
− | A Task has the following attributes:
| |
− | | |
− | * id
| |
− | * workbook_name
| |
− | * execution_id
| |
− | * name
| |
− | * description
| |
− | * action
| |
− | * state
| |
− | * tags
| |
− | | |
− | | |
− | "'''state'''" can take one of the following values:
| |
− | | |
− | * IDLE
| |
− | * RUNNING
| |
− | * SUCCESS
| |
− | * ERROR
| |
− | | |
− | | |
− | "'''tags'''" is a list of values associated with a Task which can be used for grouping tasks using some criteria.
| |
− | | |
− | ==== URL Parameters ====
| |
− | * workbook_name (string) - Workbook name.
| |
− | * execution_id (string) - Execution id.
| |
− | * id (string) - Task id.
| |
− | | |
− | ==== Model ====
| |
− | {
| |
− | "id": "12434234",
| |
− | "workbook_name": "my_deployment_workbook",
| |
− | "execution_id": "12304593450234",
| |
− | "name": "install_mc",
| |
− | "description": "Install Midnight Commander",
| |
− | "action": "install_mc",
| |
− | "state": "IDLE",
| |
− | "tags": ["deployment", "mc"]
| |
− | }
| |
− | | |
− | ==== Retrieve Task list [GET] ====
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Task list
| |
− | | |
− | '''Response example'''
| |
− | {
| |
− | "tasks": [
| |
− | {
| |
− | "description": null,
| |
− | "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
| |
− | "id": "1a5b681c-2f9f-4634-8b4c-2306e4c17b75",
| |
− | "name": "createVM",
| |
− | "state": "ERROR",
| |
− | "tags": null,
| |
− | "workbook_name": "wb"
| |
− | },
| |
− | {
| |
− | "description": null,
| |
− | "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
| |
− | "id": "bd955236-04ea-4ee9-ab1f-3068ee72c2fa",
| |
− | "name": "sendCreateVMError",
| |
− | "state": "ERROR",
| |
− | "tags": null,
| |
− | "workbook_name": "wb"
| |
− | }
| |
− | ]
| |
− | }
| |
− | | |
− | ==== Retrieve a single task [GET] ====
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Task
| |
− | | |
− | ==== Update a task [PUT] ====
| |
− | The only sensible field to update is '''"state"'''. This way applications that handle task actions can communicate task states back to Mistral.
| |
− | | |
− | * '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Task
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "id": "12434234",
| |
− | "state": "ERROR"
| |
− | }
| |