Jump to: navigation, search

Difference between revisions of "Mistral/RestAPI"

(Execution [/workbooks/{workbook_name}/executions/{id}])
 
(36 intermediate revisions by 2 users not shown)
Line 15: Line 15:
  
 
=== Workbook [/workbooks/{name}] ===
 
=== 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. ([[Mistral/DSL|DSL spec]])
+
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:
 
A Workbook has the following attributes:
Line 22: Line 22:
 
* description
 
* description
 
* tags
 
* 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.)
 
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'''
+
==== URL Parameters ====
 
* name - Workbook name.
 
* name - Workbook name.
  
 
==== Model ====
 
==== Model ====
  
        {
+
{
            "name" : "my_deployment_workbook",
+
    "name" : "my_deployment_workbook",
            "description" : "A set of tasks for deployment",
+
    "description" : "A set of tasks for deployment",
            "tags": ["deployment", "mc"]
+
    "tags": ["deployment", "mc"]
        }
+
}
  
 
==== Retrieve Workbook list [GET] ====
 
==== Retrieve Workbook list [GET] ====
Line 42: Line 43:
  
 
'''Response'''
 
'''Response'''
 
+
{
    {
+
    "workbooks": [
        "workbooks": [
+
        {
          {
 
 
             "name": "my_deployment_workbook",
 
             "name": "my_deployment_workbook",
 
             "description": "My deployment workbook",
 
             "description": "My deployment workbook",
 
             "tags": ["deployment", "mc"]
 
             "tags": ["deployment", "mc"]
          }
+
        }
        ]
+
    ]
    }
+
}
  
 
==== Retrieve a single Workbook [GET] ====
 
==== Retrieve a single Workbook [GET] ====
Line 58: Line 58:
 
* '''Returns:''' Workbook
 
* '''Returns:''' Workbook
  
Response
+
'''Response'''
 
+
{
          {
+
    "name": "my_deployment_workbook",
            "name": "my_deployment_workbook",
+
    "description": "My deployment workbook",
            "description": "My deployment workbook",
+
    "tags": ["deployment", "mc"]
            "tags": ["deployment", "mc"]
+
}
          }
 
  
 
==== Create a Workbook [POST] ====
 
==== Create a Workbook [POST] ====
Line 73: Line 72:
 
* '''Returns:''' Created Workbook
 
* '''Returns:''' Created Workbook
  
Request (application/json)
+
'''Request (application/json)'''
 
+
{
        {
+
    "name": "my_deployment_workbook",
            "name": "my_deployment_workbook",
+
    "description": "My deployment workbook",
            "description": "My deployment workbook",
+
    "tags": ["deployment", "mc"]
            "tags": ["deployment", "mc"]
+
}
        }
 
  
 
==== Update a Workbook [PUT] ====
 
==== Update a Workbook [PUT] ====
Line 88: Line 86:
 
* '''Returns:''' Updated Workbook
 
* '''Returns:''' Updated Workbook
  
* Request example
+
'''Request example'''
 
+
{
        {
+
    "name": "my_deployment_workbook",
            "name": "my_deployment_workbook",
+
    "description": "My cool deployment workbook!",
            "description": "My cool deployment workbook!",
+
    "tags": ["deployment", "mc", "new_tag"]
            "tags": ["deployment", "mc", "new_tag"]
+
}
        }
 
  
 
==== Delete a Workbook [DELETE] ====
 
==== Delete a Workbook [DELETE] ====
Line 101: Line 98:
 
* '''Status:''' 204
 
* '''Status:''' 204
 
* '''Returns:''' No content
 
* '''Returns:''' No content
 
---
 
  
 
=== Workbook Definition [/workbook/{workbook_name}/definition] ===
 
=== Workbook Definition [/workbook/{workbook_name}/definition] ===
Workbook definition is a YAML document (what is called "Mistral DSL") containing description of all entities of the workbook like action namespaces, workflow, triggers etc.
+
Workbook definition is a YAML document (what is called "Mistral DSL") containing description of all entities of the workbook like action namespaces, workflow, triggers etc. See [[Mistral/DSL|Mistral DSL Specification]] for details.
  
'''URL Parameters'''
+
==== URL Parameters ====
 
* workbook_name - Workbook name.
 
* workbook_name - Workbook name.
  
Line 133: Line 128:
 
* context
 
* context
 
* state
 
* 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:
 
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:
Line 143: Line 139:
 
* DELAYED
 
* DELAYED
  
'''URL Parameters'''
+
==== URL Parameters ====
 
* workbook_name (string) - Workbook name.
 
* workbook_name (string) - Workbook name.
 
* id (string) - Execution id.
 
* id (string) - Execution id.
  
 
==== Model ====
 
==== Model ====
 
+
{
        {
+
    "id": "12304593450234",
            "id": "12304593450234",
+
    "workbook_name": "my_deployment_workbook",
            "workbook_name" : "my_deployment_workbook",
+
    "task": "deploy_env",
            "task" : "deploy_env",
+
    "context": {
            "context": {
+
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
                "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
+
    },
            },
+
    "state": "RUNNING"
            "state" : "RUNNING"
+
}
        }
 
  
 
==== Retrieve Execution list [GET] ====
 
==== Retrieve Execution list [GET] ====
  
* '''URL:''' /workbooks/<workbook-name>/executions
+
* '''URL:''' /workbooks/{workbook-name}/executions
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' List of Executions
 
* '''Returns:''' List of Executions
Line 167: Line 162:
 
==== Retrieve a single execution [GET] ====
 
==== Retrieve a single execution [GET] ====
  
* '''URL:''' /workbooks/<workbook-name>/executions/<execution-id>
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Execution
 
* '''Returns:''' Execution
Line 174: Line 169:
 
To create a new execution simply provide a JSON structure with needed attribute values.
 
To create a new execution simply provide a JSON structure with needed attribute values.
  
* '''URL:''' /workbooks/<workbook-name>/executions
+
* '''URL:''' /workbooks/{workbook-name}/executions
 
* '''Status:''' 201
 
* '''Status:''' 201
 
* '''Returns:''' Created Execution
 
* '''Returns:''' Created Execution
  
* Request example
+
'''Request example'''
 +
{
 +
    "workbook_name": "my_deployment_workbook"
 +
    "task": "deploy_env",
 +
    "context": {
 +
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 +
    }
 +
}
  
        {
+
'''Response example'''
            "workbook_name": "my_deployment_workbook"
+
{
            "task" : "deploy_env",
+
    "id": "12304593450234",
            "context": "{}"
+
    "workbook_name": "my_deployment_workbook"
        }
+
    "target_task": "deploy_env"
 
+
    "state": "RUNNING"
* Response example
+
}
        {
 
            "id": "12304593450234",
 
            "workbook_name" : "my_deployment_workbook"
 
            "target_task" : "deploy_env"
 
            "state" : "RUNNING"
 
        }
 
  
 
==== Update an execution [PUT] ====
 
==== 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.
 
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>
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Execution
 
* '''Returns:''' Execution
  
* Request example
+
'''Request example'''
 +
{
 +
    "state": "STOPPED"
 +
}
  
        {
+
'''Response example'''
            "id": "12304593450234",
+
{
            "state": STOPPED
+
    "id": "12304593450234",
        }
+
    "workbook_name": "my_deployment_workbook",
 
+
    "task": "deploy_env",
* Response example
+
    "context": {
---
+
        "image_id": "9fa5ebb0-cf38-4d41-b667-01b13c13e894"
 +
    },
 +
    "state": "STOPPED"
 +
}
  
 
=== Task [/workbooks/{workbook_name}/executions/{execution_id}/tasks/{id}] ===
 
=== Task [/workbooks/{workbook_name}/executions/{execution_id}/tasks/{id}] ===
Line 224: Line 226:
 
* state
 
* state
 
* tags
 
* tags
 +
  
 
"'''state'''" can take one of the following values:
 
"'''state'''" can take one of the following values:
Line 231: Line 234:
 
* SUCCESS
 
* SUCCESS
 
* ERROR
 
* ERROR
 +
  
 
"'''tags'''" is a list of values associated with a Task which can be used for grouping tasks using some criteria.
 
"'''tags'''" is a list of values associated with a Task which can be used for grouping tasks using some criteria.
  
'''URL Parameters'''
+
==== URL Parameters ====
 
* workbook_name (string) - Workbook name.
 
* workbook_name (string) - Workbook name.
 
* execution_id (string) - Execution id.
 
* execution_id (string) - Execution id.
Line 240: Line 244:
  
 
==== Model ====
 
==== Model ====
 
+
{
        {
+
    "id": "12434234",
            "id": "12434234",
+
    "workbook_name": "my_deployment_workbook",
            "workbook_name" : "my_deployment_workbook",
+
    "execution_id": "12304593450234",
            "execution_id": "12304593450234",
+
    "name": "install_mc",
            "name": "install_mc",
+
    "description": "Install Midnight Commander",
            "description" : "Install Midnight Commander",
+
    "action": "install_mc",
            "action" : "install_mc",
+
    "state": "IDLE",
            "state": "IDLE",
+
    "tags": ["deployment", "mc"]
            "tags" : ["deployment", "mc"]
+
}
        }
 
  
 
==== Retrieve Task list [GET] ====
 
==== Retrieve Task list [GET] ====
  
* '''URL:''' /workbooks/<workbook-name>/executions/<execution-id>/tasks
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Task list
 
* '''Returns:''' Task list
  
* Response example
+
'''Response example'''
 
+
  {
  {  
+
    "tasks": [
    "tasks": [
+
        {
        {
+
            "description": null,
            "description": null,  
+
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",  
+
            "id": "1a5b681c-2f9f-4634-8b4c-2306e4c17b75",
            "id": "1a5b681c-2f9f-4634-8b4c-2306e4c17b75",  
+
            "name": "createVM",
            "name": "createVM",  
+
            "state": "ERROR",
            "state": "ERROR",  
+
            "tags": null,
            "tags": null,  
+
            "workbook_name": "wb"
            "workbook_name": "wb"
+
        },
        },  
+
        {
        {
+
            "description": null,
            "description": null,  
+
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",
            "execution_id": "fb2d856f-e6b0-480e-a59a-e054924cde73",  
+
            "id": "bd955236-04ea-4ee9-ab1f-3068ee72c2fa",
            "id": "bd955236-04ea-4ee9-ab1f-3068ee72c2fa",  
+
            "name": "sendCreateVMError",
            "name": "sendCreateVMError",  
+
            "state": "ERROR",
            "state": "ERROR",  
+
            "tags": null,
            "tags": null,  
+
            "workbook_name": "wb"
            "workbook_name": "wb"
+
        }
        }
+
    ]
    ]
 
 
  }
 
  }
 
  
 
==== Retrieve a single task [GET] ====
 
==== Retrieve a single task [GET] ====
  
* '''URL:''' /workbooks/<workbook-name>/executions/<execution-id>/tasks/<task-id>
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Task
 
* '''Returns:''' Task
Line 293: Line 294:
 
The only sensible field to update is '''"state"'''. This way applications that handle task actions can communicate task states back to Mistral.
 
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>
+
* '''URL:''' /workbooks/{workbook-name}/executions/{execution-id}/tasks/{task-id}
 
* '''Status:''' 200
 
* '''Status:''' 200
 
* '''Returns:''' Task
 
* '''Returns:''' Task
  
* Request example
+
'''Request example'''
 
+
{
        {
+
    "id": "12434234",
            "id": "12434234",
+
    "state": "ERROR"
            "state": "ERROR",
+
}
        }
 

Latest revision as of 13:22, 6 June 2014

Mistral API v1.0

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 resources states. Future specifications may also support YAML, XML or other types. The only one place where YAML is used is Mistral DSL for describing Mistral workbooks which contain tasks, dependencies and transitions between them, actions, triggers and other entities related to workflow execution.

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 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

Workbook Definition [/workbook/{workbook_name}/definition]

Workbook definition is a YAML document (what is called "Mistral DSL") containing description of all entities of the workbook like action namespaces, workflow, triggers etc. See Mistral DSL Specification for details.

URL Parameters

  • workbook_name - Workbook name.

Retrieve a workbook definition [GET]

  • URL: /workbook/{workbook_name}/definition
  • Status: 200
  • Returns: Mistral DSL document

Upload a workbook definition [PUT]

  • URL: /workbook/{workbook_name}/definition
  • Status: 201
  • Returns: Mistral DSL document
  • Content-Type: text/plain

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"
}