Difference between revisions of "Mistral/RestAPI"

Revision as of 09:11, 23 May 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 between them, actions, events 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 between them, actions, events 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. **(TBD: link to DSL spec)**

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
• 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: /workbook
• 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 (application/json)

       {
           "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 tasks, actions, events and so on.

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
• target_task
• state

Note that id is immutable and automatically assigned by Mistral at creation time. state can take one of the following values:

• RUNNING
• SUSPENDED
• STOPPED
• SUCCESS
• ERROR

target_task defines what to run in a workbook. Once a user has let Mistral know what the target task is, Mistral determines a subgraph of the full task graph in the workbook that needs to be executed in order to reach the target task (dependencies of the target task, dependencies of the dependencies and all the way down to the tasks that don't have any dependencies).

URL Parameters

• workbook_name (string) - Workbook name.
• id (string) - Execution id.

Model

       {
           "id": "12304593450234",
           "workbook_name" : "my_deployment_workbook"
           "target_task" : "deploy_env"
           "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

       {
           "task" : "deploy_env",
           "context": "{}"
       }

• 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

       {
           "id": "12304593450234",
           "state": STOPPED
       }

• Response example

---

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

+ Request (application/json)

       {
           "id": "12434234",
           "state": "ERROR",
       }

+ Response 200 (application/json)

   [Task][]

---