Difference between revisions of "Mistral/RestAPIv2"

Revision as of 05:32, 25 September 2014

Mistral API v2.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 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 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: /workbook/{workbook_name}
• Status: 200
• Returns: Updated Workbook

Request example

{
    "definition" : "HERE GOES WORKBOOK DEFINITION IN MISTRAL DSL v2",
}

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