Difference between revisions of "Mistral/RestAPIv2"
(→Task [/tasks/{id}]) |
(→Mistral API v2) |
||
Line 534: | Line 534: | ||
* '''Status:''' 200 | * '''Status:''' 200 | ||
* '''Returns:''' Action Execution list | * '''Returns:''' Action Execution list | ||
+ | |||
+ | |||
+ | === Action Execution [/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 | ||
+ | * DELAYED | ||
+ | |||
+ | ==== 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" | ||
+ | } |
Revision as of 08:49, 6 May 2015
Contents
Mistral API v2
NOTE: API described in this document might slightly change within a short period of time (2-3 weeks) and should be now considered experimental. Mistral team is now actively working on stabilization.
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.
API v2 Root [/v2/]
All API v2 urls are relative to API v2 root.
Workbook [/workbooks/{name}]
See what 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 YAML structure containing workbook definition as a string value.
- URL: /workbooks
- Status: 201
- Returns: Created Workbook
Request (text/plain)
<HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
Example:
Request (text/plain)
--- version: 2.0 workflows: tasks: task1: action: std.echo output="Hello world!"
Update a Workbook [PUT]
To modify a workbook simply send a YAML structure containing workbook definition as a string value.
- URL: /workbooks
- Status: 200
- Returns: Updated Workbook
Request example
<HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
Validate a Workbook [POST]
To modify a workbook simply send a YAML structure containing workbook definition as a string value.
- URL: /workbooks/validate
- Status: 200
- Returns: JSON containing 'valid' boolean key meaning whether valid given workbook or not.
Request example
<HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2>
Response example
{ "valid": true }
Delete a Workbook [DELETE]
- URL: /workbooks/{workbook_name}
- Status: 204
- Returns: No content
Workflow [/workflows/{name}]
See what 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 YAML structure containing workflow definition as a string value.
- URL: /workflows
- Status: 201
- Returns: List of created Workflows
Request (text/plain)
<HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
Request example (text/plain)
--- version: 2.0 my_workflow: tasks task1: action: std.echo output="Hello World!"
Update a Workflow(s) [PUT]
To modify a workflow simply send a YAML structure containing workflow definition as a string value.
- URL: /workflows
- Status: 200
- Returns: List of Updated Workflows
Request example (text/plain)
<HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
Validate a Workflow [POST]
To modify a workbook simply send a YAML structure containing workflow definition as a string value.
- URL: /workflows/validate
- Status: 200
- Returns: JSON containing 'valid' boolean key meaning whether valid given workbook or not.
Request example
<HERE GOES ONE ORE MORE WORKFLOW DEFINITIONS IN MISTRAL DSL v2>
Response example
{ "valid": true }
Delete a Workflow [DELETE]
- URL: /workflow/{workflow_name}
- Status: 204
- Returns: No content
Action [/actions/{name}]
See what Actions are in Mistral DSL v2 Specification.
Action has the following attributes:
- id
- name
- description
- definition
- created_at
- updated_at
name is immutable. Note that name and description get inferred from action definition when Mistral service receives a POST request. So they can't be changed in another way.
URL Parameters
- name - Action name.
Model
{ "name" : "my_action", "description": "My cool action", "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2", "created_at" : "2014-09-25 03:35:36", "updated_at" : "2014-09-25 03:35:36", }
Retrieve Action list [GET]
- URL: /action
- Status: 200
- Returns: List of Actions
Response
{ "actions": [ { "name" : "my_action", "description": "My custom ad-hoc action", "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2", "created_at" : "2014-09-25 03:35:36", "updated_at" : "2014-09-25 03:35:36", } ] }
Retrieve a single Action [GET]
- URL: /actions/{action_name}
- Status: 200
- Returns: Action
Response
{ "name" : "my_action", "description": "My ad-hoc action", "definition" : "HERE GOES ACTION DEFINITION IN MISTRAL DSL v2", "created_at" : "2014-09-25 03:35:36", "updated_at" : "2014-09-25 03:35:36", }
Create a Action(s) [POST]
To create a new Action simply provide a JSON structure containing attribute 'definition' and its value.
- URL: /actions
- Status: 201
- Returns: List of created Actions
Request (application/json)
{ "definition" : "HERE GOES ONE ORE MORE ACTION DEFINITIONS IN MISTRAL DSL v2", }
Update a Action(s) [PUT]
To modify an Action simply send a JSON structure containing attribute 'definition' and its value.
- URL: /actions
- Status: 200
- Returns: List of updated Actions
Request example
{ "definition" : "HERE GOES ONE ORE MORE ACTION DEFINITIONS IN MISTRAL DSL v2", }
Delete a Action [DELETE]
- URL: /action/{action_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, 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:
- RUNNING
- SUCCESS
- ERROR
- PAUSED
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
- workflow_name
- workflow_execution_id
- result
- published
- created_at
- updated_at
"state" can take one of the following values:
- IDLE
- RUNNING
- SUCCESS
- ERROR
- DELAYED
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
- URL: /tasks/{task-id}/action_executions
- Status: 200
- Returns: Action Execution list
Action Execution [/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
- DELAYED
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" }