|
|
(16 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}] ===
| |
− | | |
− | See what [[Mistral/DSLv2#Workbooks|Workbooks]] are in Mistral DSL v2 Specification.
| |
− | | |
− | A Workbook has the following attributes:
| |
− | | |
− | * id
| |
− | * name
| |
− | * tags
| |
− | * definition
| |
− | * created_at
| |
− | * updated_at
| |
− | | |
− | '''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.
| |
− | | |
− | ==== URL Parameters ====
| |
− | | |
− | * name - Workbook name.
| |
− | | |
− | ==== Model ====
| |
− | | |
− | {
| |
− | "name" : "my_deployment_workbook",
| |
− | "tags": ["deployment", "mc"],
| |
− | "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | | |
− | ==== Retrieve Workbook list [GET] ====
| |
− | * '''URL:''' /workbooks
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' List of workbooks
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "workbooks": [
| |
− | {
| |
− | "name" : "my_deployment_workbook",
| |
− | "tags": ["deployment", "mc"],
| |
− | "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | ]
| |
− | }
| |
− | | |
− | ==== Retrieve a single Workbook [GET] ====
| |
− | * '''URL:''' /workbooks/{workbook_name}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Workbook
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "name" : "my_deployment_workbook",
| |
− | "tags": ["deployment", "mc"],
| |
− | "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | | |
− | ==== Create a Workbook [POST] ====
| |
− | To create a new Workbook simply provide a JSON structure containing attribute 'definition' and its value.
| |
− | | |
− | * '''URL:''' /workbooks
| |
− | * '''Status:''' 201
| |
− | * '''Returns:''' Created Workbook
| |
− | | |
− | '''Request (application/json)'''
| |
− | {
| |
− | "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
| |
− | }
| |
− | | |
− | ==== Update a Workbook [PUT] ====
| |
− | To modify a workbook simply send a JSON structure containing attribute 'definition' and its value.
| |
− | | |
− | * '''URL:''' /workbooks
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Updated Workbook
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
| |
− | }
| |
− | | |
− | ==== Delete a Workbook [DELETE] ====
| |
− | | |
− | * '''URL:''' /workbooks/{workbook_name}
| |
− | * '''Status:''' 204
| |
− | * '''Returns:''' No content
| |
− | | |
− | === Workflow [/workflows/{name}] ===
| |
− | | |
− | See what [[Mistral/DSLv2#Workflows|Workflows]] are in Mistral DSL v2 Specification.
| |
− | | |
− | A Workflow has the following attributes:
| |
− | | |
− | * id
| |
− | * name
| |
− | * tags
| |
− | * definition
| |
− | * created_at
| |
− | * updated_at
| |
− | | |
− | '''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.
| |
− | | |
− | ==== URL Parameters ====
| |
− | | |
− | * name - Workflow name.
| |
− | | |
− | ==== Model ====
| |
− | | |
− | {
| |
− | "name" : "my_workflow",
| |
− | "tags": ["deployment", "mc"],
| |
− | "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | | |
− | ==== Retrieve Workflow list [GET] ====
| |
− | * '''URL:''' /workflows
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' List of Workflows
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "workflows": [
| |
− | {
| |
− | "name" : "my_workflow",
| |
− | "tags": ["deployment"],
| |
− | "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | ]
| |
− | }
| |
− | | |
− | ==== Retrieve a single Workflow [GET] ====
| |
− | * '''URL:''' /workflows/{workflows_name}
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' Workflow
| |
− | | |
− | '''Response'''
| |
− | {
| |
− | "name" : "my_workflow",
| |
− | "tags": ["deployment"],
| |
− | "definition" : "HERE GOES WORKFLOW DEFINITION IN MISTRAL DSL v2",
| |
− | "created_at" : "2014-09-25 03:35:36",
| |
− | "updated_at" : "2014-09-25 03:35:36",
| |
− | }
| |
− | | |
− | ==== Create a Workflow(s) [POST] ====
| |
− | To create a new Workflow simply provide a JSON structure containing attribute 'definition' and its value.
| |
− | | |
− | * '''URL:''' /workflows
| |
− | * '''Status:''' 201
| |
− | * '''Returns:''' List of created Workflows
| |
− | | |
− | '''Request (application/json)'''
| |
− | {
| |
− | "definition" : "HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2",
| |
− | }
| |
− | | |
− | ==== Update a Workflow(s) [PUT] ====
| |
− | To modify a workflow simply send a JSON structure containing attribute 'definition' and its value.
| |
− | | |
− | * '''URL:''' /workflows
| |
− | * '''Status:''' 200
| |
− | * '''Returns:''' List of Updated Workflows
| |
− | | |
− | '''Request example'''
| |
− | {
| |
− | "definition" : "HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2",
| |
− | }
| |
− | | |
− | ==== Delete a Workflow [DELETE] ====
| |
− | | |
− | * '''URL:''' /workflow/{workflow_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"
| |
− | }
| |