Difference between revisions of "Mistral/RestAPIv2"

Revision as of 05:04, 25 September 2014

Mistral API v2.0

TODO

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

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

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