-
Notifications
You must be signed in to change notification settings - Fork 3
JSON API Documentation
Taverna Player has a RESTful JSON interface so that you can use it like any other Web Service.
Currently the only resources that are exposed by the REST interface are workflows and runs. The host application in which Taverna Player is running may override anything and can also provide access to other resources that it controls as well. You should consult any documentation that comes with the host application as well as this page.
There is more information about JSON at http://json.org/.
When accessing the Taverna Player JSON API you must explicitly request a response in JSON format. If you do not then it will assume that you want HTML and return that instead.
To request JSON you must set the Accept header in your request to
application/json.
Accept: application/json
The rest of this documentation assumes that the Accept header is set as
above for all requests.
For those API entries that require data to be uploaded this should also be done in JSON format. In this case you must ensure that your request specifies that the content type of the body of your request is JSON.
Do this by setting the Content-Type header of your request to
application/json.
Content-Type: application/json
The rest of this documentation assumes that the Content-Type header is set
as above for all requests.
Taverna Player does not provide user authentication itself but it is highly likely that the host application within which it is running will. Please see the documentation for the host application for its requirements.
The URI at which Taverna Player's resources are accessed will depend on where it has been mounted within its host application. This documentation assumes that it has been mounted at the root of the host for brevity, e.g.
http://example.com/
But it may have been mounted at a different location in the host application, e.g.
http://example.com/taverna/
Please consult the host application's documentation to ascertain where Taverna Player's resources may be found.
The JSON data that is returned by Taverna Player is mostly very simple; nested structures are avoided if possible. As lists of runs can get very long only summary information about each run is returned unless the run is directly accessed by its id, in which case full details are given.
In the vast majority of cases the JSON output directly reflects the models that Taverna Player uses to represent runs, inputs and outputs. See the API documentation for more details.
Note that the host application can add/remove/override any fields in the examples below. If this is the case then you will need to consult its own documentation as well as this.
By default Taverna Player's workflow data is minimal as the workflow model is expected to be overridden by the host application.
{
"id": 1,
"title": "Hello, World!",
"author": "Alan, et al.",
"description": "Say 'Hello, World!'"
}Fields for default workflow data:
| Field | Meaning |
|---|---|
| id | The id of the workflow within the host application |
| title | The title of the workflow |
| author | The author, or authors who created the workflow |
| description | A (possibly) detailed description of what the workflow does. |
Minimal data to describe a run.
{
"id": 7,
"name": "Pipelined list iteration run #1",
"workflow_id": 3,
"state": "finished",
"start_time": "2014-03-07T11:25:51Z",
"finish_time": "2014-03-07T11:26:04Z"
}Fields in the summary data:
| Field | Meaning |
|---|---|
| id | The id of the run within the host application |
| name | A short textual memonic for the run |
| workflow_id | The id of the run's workflow within the host application |
| state | The internal state of the run |
| start_time | The time the run started executing |
| finish_time | The time the run finished executing |
Full run description.
{
"id": 7,
"name": "Pipelined list iteration run #1",
"workflow_id": 3,
"state": "finished",
"start_time": "2014-03-07T11:25:51Z",
"finish_time": "2014-03-07T11:26:04Z",
"status_message": "Finished",
"inputs":
[
{
"name": "input",
"depth": 0,
"value_type": "text/plain",
"value_size": null,
"path": "/runs/7/input/input"
}
],
"outputs":
[
{
"name": "out",
"depth": 1,
"value_type": ["text/plain", "text/plain", "text/plain", "text/plain"],
"value_size": [15, 15, 15, 15],
"path": "/runs/7/output/out"
}
],
"outputs_zip": "/runs/7/download/results",
"log": "/runs/7/download/log"
}Extra fields in the full representation:
| Field | Meaning |
|---|---|
| status_message | A human friendly description of the run status |
| inputs | A list of run inputs (described below) |
| outputs | A list of run outputs (described below) |
| outputs_zip | The path to a zip file containing all of the run outputs |
| log | The path to a Taverna Server log for the run execution |
The paths given by outputs_zip and log above are absolute paths from the
base URI of the server.
Inputs and outputs share the same data format:
{
"name": "out",
"depth": 1,
"value_type": ["text/plain", "text/plain", "text/plain", "text/plain"],
"value_size": [15, 15, 15, 15],
"path": "/runs/7/output/out"
}Fields for input/output data:
| Field | Meaning |
|---|---|
| name | The name of the port from the parent workflow |
| depth | The depth of the port - 0 for a singleton value, 1 for a list |
| value_type | The MIME type of the value in the port |
| value_size | The size of the value |
| path | The absolute path from which to download the port data |
This section describes each of the entry points in the API with example requests and responses.
Returns all workflows in a list.
GET http://example.com/workflows
Status code: 200 (OK)
[{
"id": 1,
"title": "Hello, World!",
"author": "Alan, et al.",
"description": "Say 'Hello, World!'"
}, {
"id": 3,
"title": "Multi Interaction",
"author": "Robert Haines",
"description": "Multiple interactions for testing."
}]Returns all runs in a list.
GET http://example.com/runs
Status code: 200 (OK)
[{
"id": 1,
"name": "Hello, World!",
"workflow_id": 1,
"state": "finished",
"start_time": "2014-03-07T11:25:51Z",
"finish_time": "2014-03-07T11:26:04Z"
}, {
"id": 4,
"name": "Interaction test",
"workflow_id": 3,
"state": "running",
"start_time": "2014-03-07T12:58:22Z",
"finish_time": null
}]Returns detailed information about a single run.
The run id to be queried is passed in the URI.
GET http://example.com/runs/1
Status code: 200 (OK)
{
"id": 1,
"name": "A workflow run 24 Jan 2014 12:01:45 UTC",
"workflow_id": 7,
"state": "finished",
"start_time": "2014-01-24T12:01:51Z",
"finish_time": "2014-01-24T12:02:03Z",
"status_message": "Finished",
"inputs": [],
"outputs":
[
{
"name": "Message",
"depth": 0,
"type": "text/plain",
"size": 718,
"uri": "/runs/1/output/Message"
}
],
"outputs_zip": "/runs/1/download/results",
"log": "/runs/1/download/log"
}Returns a JSON document that you can fill in to create a run with the POST end-point, below.
workflow_id needs to be specified. What this is will depend on the host
application.
GET http://example.com/runs/new?workflow_id=3
Status code: 200 (OK)
The returned document can be customized and used for creating a run.
{
"run": {
"workflow_id": 3,
"name": "Pipelined list iteration",
"inputs_attributes":
[
{
"name": "input",
"value": "150"
}
]
}
}| Field | Meaning | Customizable? |
|---|---|---|
| run | The container for the run data | - |
| workflow_id | The id of the workflow that you want to run. | No |
| name | A human readable/rememberable name for the new run. This defaults to the title of the workflow. | Yes |
| inputs_attributes | A list of name-value pairs for setting workflow inputs | - |
| inputs_attibutes name | The name of the input to set | No |
| inputs_attributes value | The value to set the input to. This defaults to an example value if the workflow provides one | Yes |
inputs_attributes will not be present if the workflow has no inputs.
Create a run.
Data is passed in the request body.
POST http://example.com/runs
{
"run" :
{
"workflow_id" : 1,
"name" : "My Run",
"inputs_attributes" :
[
{
"name" : "input",
"value" : 15
}
]
}
}| Field | Meaning | Required? |
|---|---|---|
| run | The container for run data | Yes |
| workflow_id | The id of the workflow to be run | Yes |
| name | A human readable/rememberable name for the new run | No |
| inputs_attributes | Data to set the run input ports if it has them | Yes if the workflow has inputs, No if not |
See the documentation for /runs/new above for more information about the
inputs_attributes field.
Status code: 201 (Created)
{
"id": 2,
"name": "My Run",
"workflow_id": 1,
"state": "pending",
"start_time": null,
"finish_time": null,
"inputs":
[
{
"name": "input",
"depth": 0,
"value_type": "text/plain",
"value_size": null,
"path": "/runs/2/input/input"
}
]
}Delete a run.
DELETE http://example.com/runs/1
Status code: 204 (No Content)
There is no response body for a DELETE.