|
|
| (21 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | == Mistral API v2.0 == | + | == This Wiki is no longer maintained == |
| | | | |
| − | This API describes the ways of interacting with Mistral service via HTTP protocol using Representational State Transfer concept (ReST).
| + | Please see the [https://docs.openstack.org/mistral/latest/api/index.html Mistral API documentation]. |
| − | | |
| − | === 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.
| |
| − | | |
| − | === 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 [/executions/{id}] ===
| |
| − | A particular workflow execution.
| |
| − | | |
| − | An Execution has the following attributes:
| |
| − | | |
| − | * id
| |
| − | * workflow_name
| |
| − | * params
| |
| − | * input
| |
| − | * output
| |
| − | * state
| |
| − | * created_at
| |
| − | * updated_at
| |
| − | | |
| − | Note that '''id''' is immutable and automatically assigned by Mistral at creation time. '''params''' define workflow type specific parameters. For example, [[mistral/DSLv2#Reverse_Workflow|reverse workflow]] takes one parameter 'task_name' that defines a target task. '''input''' is a JSON structure containing workflow input values. '''output''' is a workflow output. '''state''' can take one of the following values:
| |
| − | | |
| − | * IDLE
| |
| − | * RUNNING
| |
| − | * SUCCESS
| |
| − | * ERROR
| |
| − | * PAUSED
| |
| − | * DELAYED
| |
| − | | |
| − | ==== URL Parameters ====
| |
| − | * id (string) - Execution id.
| |
| − | | |
| − | ==== Model ====
| |
| − | {
| |
| − | "id": "12304593450234",
| |
| − | "workflow_name": "my_workflow",
| |
| − | "params": {},
| |
| − | "input": {
| |
| − | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
| − | },
| |
| − | "output": {
| |
| − | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
| − | },
| |
| − | "state": "RUNNING",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | }
| |
| − | | |
| − | ==== Retrieve Execution list [GET] ====
| |
| − | | |
| − | * '''URL:''' /executions
| |
| − | * '''Status:''' 200
| |
| − | * '''Returns:''' List of Executions
| |
| − | | |
| − | ==== Retrieve a single execution [GET] ====
| |
| − | | |
| − | * '''URL:''' /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:''' /executions
| |
| − | * '''Status:''' 201
| |
| − | * '''Returns:''' Created Execution
| |
| − | | |
| − | '''Request example'''
| |
| − | {
| |
| − | "workflow_name": "my_workflow"
| |
| − | "input": {
| |
| − | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
| − | }
| |
| − | }
| |
| − | | |
| − | '''Response example'''
| |
| − | {
| |
| − | "id": "12304593450234",
| |
| − | "workflow_name": "my_workflow"
| |
| − | "params": {},
| |
| − | "input": {
| |
| − | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
| − | },
| |
| − | "output": {},
| |
| − | "state": "RUNNING",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | }
| |
| − | | |
| − | ==== 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.
| |
| − | | |
| − | * '''URL:''' /executions/{execution-id}
| |
| − | * '''Status:''' 200
| |
| − | * '''Returns:''' Execution
| |
| − | | |
| − | '''Request example'''
| |
| − | {
| |
| − | "state": "PAUSED"
| |
| − | }
| |
| − | | |
| − | '''Response example'''
| |
| − | {
| |
| − | "id": "12304593450234",
| |
| − | "workflow_name": "my_workflow"
| |
| − | "params": {},
| |
| − | "input": {
| |
| − | "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
| |
| − | },
| |
| − | "output": {},
| |
| − | "state": "PAUSED",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | }
| |
| − | | |
| − | === Task [/tasks/{id}] ===
| |
| − | 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.
| |
| − | | |
| − | A Task has the following attributes:
| |
| − | | |
| − | * id
| |
| − | * name
| |
| − | * wf_name
| |
| − | * execution_id
| |
| − | * result
| |
| − | * input
| |
| − | * output
| |
| − | * created_at
| |
| − | * updated_at
| |
| − | | |
| − | "'''state'''" can take one of the following values:
| |
| − | | |
| − | * IDLE
| |
| − | * RUNNING
| |
| − | * SUCCESS
| |
| − | * ERROR
| |
| − | | |
| − | ==== URL Parameters ====
| |
| − | * id (string) - Task id.
| |
| − | | |
| − | ==== Model ====
| |
| − | {
| |
| − | "id": "12434234",
| |
| − | "name": "create_vm",
| |
| − | "workflow_name": "my_workflow",
| |
| − | "execution_id": "12304593450234",
| |
| − | "input": {
| |
| − | "image_id": "1-2-3-4"
| |
| − | },
| |
| − | "state": "RUNNING",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | }
| |
| − | | |
| − | ==== Retrieve Task list [GET] ====
| |
| − | | |
| − | * '''URL:''' /tasks
| |
| − | * '''Status:''' 200
| |
| − | * '''Returns:''' Task list
| |
| − | | |
| − | '''Response example'''
| |
| − | {
| |
| − | "tasks": [
| |
| − | {
| |
| − | "id": "12434234",
| |
| − | "name": "create_vm",
| |
| − | "workflow_name": "my_workflow",
| |
| − | "execution_id": "12304593450234",
| |
| − | "input": {
| |
| − | "image_id": "1-2-3-4"
| |
| − | },
| |
| − | "state": "SUCCESS",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | },
| |
| − | {
| |
| − | "id": "12434235",
| |
| − | "name": "associate_ip",
| |
| − | "workflow_name": "my_workflow",
| |
| − | "execution_id": "12304593450234",
| |
| − | "input": {
| |
| − | "vm_id": "1-2-3-4"
| |
| − | },
| |
| − | "state": "RUNNING",
| |
| − | "created_at": "2014-09-25 03:35:36",
| |
| − | "updated_at": "2014-09-25 03:35:36"
| |
| − | },
| |
| − | ]
| |
| − | }
| |
| − | | |
| − | ==== Retrieve a single task [GET] ====
| |
| − | | |
| − | * '''URL:''' /tasks/{task-id}
| |
| − | * '''Status:''' 200
| |
| − | * '''Returns:''' Task
| |
| − | | |
| − | ==== Update a task [PUT] ====
| |
| − | The only two sensible fields to update are '''"state"''' and '''"result"'''. When using asynchronous processing they can be used to notify Mistral with task state and result.
| |
| − | | |
| − | * '''URL:''' /tasks/{task-id}
| |
| − | * '''Status:''' 200
| |
| − | * '''Returns:''' Task
| |
| − | | |
| − | '''Request example'''
| |
| − | {
| |
| − | "id": "12434234",
| |
| − | "state": "ERROR"
| |
| − | }
| |
