Taverna has now moved to the Apache Software Foundation. For updated information, see Apache Taverna (incubating).

REST API

Note that schemas in this document are actually pseudo-schemas. For example, this shows how the various marks on attributes and elements indicate their cardinality and type:

<element requiredAttr="xsd:someType">
    <requiredChildElement />

    <zeroOrMoreChildren /> *
    <alternative1 /> | <alternative2 />

    <childWithSimpleStringContent>
        xsd:string
    </childWithSimpleStringContent>

    <childWithUndescribedContent ... />
</element>

To be exact, a suffix of * marks an element that can be repeated arbitrarily often, and otherwise exactly one of the element is required. We never use cardinalities other than these, and order is always respected. Where there is complex content, it will either be described inline or separately. Where there is a choice between two elements, they are separated by a | character.

Namespaces are always defined as follows; their definitions are omitted from the pseudoschemas:

Prefix Namespace URI
t2flow http://taverna.sf.net/2008/xml/t2flow
t2s http://ns.taverna.org.uk/2010/xml/server/
t2sr http://ns.taverna.org.uk/2010/xml/server/rest/
xlink http://www.w3.org/1999/xlink
xsd http://www.w3.org/2001/XMLSchema

Main Server Resource

Relative URI Operation Description Response Codes
/ GET Retrieves a description of the Server as either XML or
JSON (determined by content negotiation) that indicates
other locations to find sub-resources.

Result format:

<t2sr:serverDescription>
    <t2sr:runs xlink:href="xsd:anyURI">
        <t2sr:run xlink:href="xsd:anyURI" /> *
    </t2sr:runs>
    <t2sr:runLimit xlink:href="xsd:anyURI" />
    <t2sr:permittedWorkflows
            xlink:href="xsd:anyURI" />
    <t2sr:permittedListeners
            xlink:href="xsd:anyURI" />
</t2sr:serverDescription>
 200
/runs GET Retrieves a list of workflow runs on the Server that the
current user is allowed to see. The value is returned as
either XML or JSON (determined by content negotiation).

Result format:

<t2sr:runList>
    <t2sr:run xlink:href="xsd:anyURI" /> *
</t2sr:runList>
 200
POST Accepts a wrapped t2flow document (as an XML child
element of a t2s:workflow element) and creates a
workflow run from it. The redirect on 202 is to the
created workflow run resource.

Input format:

<t2s:workflow>
    <t2flow:workflow ... />
</t2s:workflow>
 201, 403
/policy/runLimit GET Returns the number of simultaneous workflow runs
that the user may create.

Result format:

xsd:int
 200
/policy/permittedWorkflows GET Retrieves a description of the workflows that the
current user may instantiate as either XML or JSON
(determined by content negotiation). If the list is
empty, any workflow may be instantiated.

Result format:

<t2sr:permittedWorkflows>
    <t2s:workflow>
        <t2flow:workflow ... />
    </t2s:workflow> *
</t2sr:permittedWorkflows>
 200
/policy/permittedListener
Types		 GET Retrieves a description of the tpyes of listeners that
may be attached to a workflow run by the current
user as either XML or JSON (determined by content
negotiation).

Result format:

<t2sr:permittedListeners>
    <t2sr:type>
        xsd:string
    </t2sr:type> *
</t2sr:permittedListeners>
 200

Workflow Run Resource

Each workflow run is a resource that is located at /runs/{uuid} relative to the main Server; all access to resources associated with a particular run is subject to user-based access control and hence may fail with a 403 Forbidden response.

Relative URI Operation Description Response Codes
/ GET Retrieves a description of the run as either XML or JSON
(determined by content negotiation) that indicates other
locations to find sub-resources.

Result format:

<t2sr:runDescription>
   <t2sr:expiry xlink:href="xsd:anyURI">
       xsd:dateTime
   </t2sr:expiry>
   <t2sr:creationWorkflow xlink:href="xsd:anyURI" />
   <t2sr:createTime xlink:href="xsd:anyURI" />
   <t2sr:startTime xlink:href="xsd:anyURI" />
   <t2sr:finishTime xlink:href="xsd:anyURI" />
   <t2sr:status xlink:href="xsd:anyURI" />
   <t2sr:workingDirectory xlink:href="xsd:anyURI" />
   <t2sr:inputs xlink:href="xsd:anyURI" />
   <t2sr:output xlink:href="xsd:anyURI" />
   <t2sr:securityContext xlink:href="xsd:anyURI" />
   <t2sr:listeners xlink:href="xsd:anyURI">
       <t2sr:listener xlink:href="xsd:anyURI" /> *
   </t2sr:listeners>
</t2sr:runDescription>
 200
DELETE Destroys this workflow run, cleaning up all underlying
resources associated with it.		 202, 403
/workflow GET Retrieves a description of the workflow used to create
the run as either XML or JSON (determined by content
negotiation).

Result format:

<t2s:workflow>
    <t2flow:workflow ... />
</t2s:workflow>
 200
/expiry GET Retrieves (as an ISO-8601 timestamp) the moment
when the workflow run will expire and become
eligible for automatic deletion.

Result format (plain text):

xsd:dateTime
 200
PUT Sets the workflow run expiry moment to the given
ISO-8601 timestamp. Responds with the new current
timestamp.

Input/result format (plain text):

xsd:dateTime
 200, 403
/createTime GET Retrieves (as an ISO-8601 timestamp) the moment
that the workflow run was created.

Result format (plain text):

xsd:dateTime
 200
/startTime GET Retrieves (as an ISO-8601 timestamp) the moment
that the workflow run was first started.

Result format (plain text):

xsd:dateTime

or empty for “never”

 200
/finishTime GET Retrieves (as an ISO-8601 timestamp) the moment
that the workflow run was discovered to have finished.

Result format:

xsd:dateTime

or empty for “never”

 200
/status GET Retrieves (as plain text) the current status of the
workflow, which will be one of these states:
* Initialized The workflow run is not yet started.
This is initial state, which allows for upload of auxiliary
data (e.g., input files).
* OperatingThe workflow run is executing normally.
* Stopped The workflow run has been halted and needs
to be manually moved back into

* Operating to continue executing.
* Finished The workflow run has executed to completion.
This is the final state, and allows for retrieving the results.

 200
PUT Attempts to set the workflow run’s status to the
given state value (plain text, one of the set listed
above), returning the state that it was actually set to.		 200, 403
/owner GET Retrieves the name of the owner of the workflow
run. (Whether or not you can see other people’s
workflow runs is a site policy decision.)

Result format:

xsd:string
 200
/wd
{/path...}		 GET Retrieves the given file (as binary) or lists the given
directory’s contents, or retrieves a directory’s contents
(including subdirectories) as a ZIP file. Which is done
depends on content negotiation; asking for
application/octet-stream gets a file contents (only for
files), asking for application/xml or application/json
does a listing (only for directories), and asking for
application/zip retrieves a ZIPped directory.

Result format (when retrieving a listing):

<t2sr:directoryContents>
    <t2s:dir xlink:href="xsd:anyURI"
t2s:name="xsd:string">
        xsd:string
    </t2s:dir> *
    <t2s:file xlink:href="xsd:anyURI"
t2s:name="xsd:string">
        xsd:string
    </t2s:file> *
</t2sr:directoryContents>

Note that the dir and file entries may be in any order
and interleaved, the name attribute is a human-readable
form of the name that is not guaranteed to be unique
within a run, and the content of the elements is a name
that is unique within the workflow run.

 200, 406
POST Creates or updates the given file, or creates a subdirectory
of the given directory, dependent on the nature of the
message provided (in XML or JSON).

Input format (create/update file):

<t2sr:upload t2sr:name="xsd:string">
    xsd:base64Binary
</t2sr:upload>

Input format (make directory):

<t2sr:mkdir t2sr:name="xsd:string" />
 201, 303, 403
DELETE Attempts to delete the file or directory indicated by the
path. The working directory may not be deleted by this
mechanism; it can only be deleted by deleting the whole
workflow run.		 202, 403
/input GET Retrieves a description of what inputs are known about
for this workflow run (as XML or JSON).

Result format:

<t2sr:runInputs>
   <t2sr:baclava xlink:href="xsd:anyURI" />
   <t2sr:input xlink:href="xsd:anyURI" /> *
</t2sr:runInputs>
 200
/input/baclava GET Retrieves a string with the name (relative to the working
directory) of the file that contains the baclava document
describing inputs for this workflow run. If empty, no baclava
document will be used. If not empty, the file must exist
when the workflow run is started.

Result format:

xsd:string
 200
PUT Sets what baclava file will be the inputs to the workflow
run. Overrides individually-specified inputs. Returns what
the resource was set to.

Input/result format:

xsd:string
 200, 403
/input
/input
/{name}		 GET Retrieves a description with either the name (relative to the
working directory) of the file that contains the value(s), or
the literal plain text input value for the input to this workflow
run called name.

Result format:

<t2sr:runInput t2sr:name="xsd:string">
    <t2sr:file>xsd:string</t2sr:file>
    |
    <t2sr:value>xsd:string</t2sr:value>
</t2sr:runInput>

Exactly one of file and value will be present.

 200
PUT Sets what literal value or file (relative to the run working
directory) that will hold the value(s) for the input to the
workflow run called name. Overrides the input baclava file
setting.

Input/Result format:

<t2sr:runInput t2sr:name="xsd:string">
    <t2sr:file>xsd:string</t2sr:file>
    |
    <t2sr:value>xsd:string</t2sr:value>
</t2sr:runInput>

Exactly one of file and value must be present.

 200, 403
/output GET Retrieves a string with the name (relative to the working
directory) of the file that contains the baclava document
that will hold the output from this workflow run. If empty,
no baclava document will be used. If empty, the outputs
will be stored in the directory out beneath the run working
directory.

Result format:

xsd:string
 200
PUT Sets what baclava file will hold the outputs from the workflow
run. Returns what baclava file will be used.

Input/result format:

xsd:string
 200, 403
/listeners GET Lists (and identifies the locations of their resources) the listeners
attached to this workflow run.

Result format:

<t2sr:listeners>
    <t2sr:listener xlink:href="xsd:anyURI"
            t2sr:name="xsd:string"
            t2sr:type="xsd:string">
        <t2sr:configuration xlink:href="xsd:anyURI" />
        <t2sr:properties>
            <t2sr:property
            t2sr:name="xsd:string"
                    xlink:href="xsd:anyURI" /> *
        </t2sr:properties>
    </t2sr:listener> *
</t2sr:listeners>
 200
POST Attaches a new listener to this workflow run.

Input format:

<t2sr:listenerDefinition t2sr:type="xsd:string">
    xsd:string
</t2sr:listenerDefinition>
 201, 403

Workflow Run Listener Resource

Each workflow run is a resource that is located at /runs/{uuid}/listeners/{name} relative to the main Server, or at /listeners/{name} relative to the workflow run; all access to resources associated with a particular run is subject to user-based access control and hence may fail with a 403 Forbidden response.

Relative URI Operation Description Response Codes
/ GET Retrieves a description of the listener as either XML or JSON (determined by content negotiation) that indicates other locations to find sub-resources.

Result format:

<t2sr:listenerDescription t2sr:name="xsd:string"
        t2sr:type="xsd:string">
    <t2sr:configuration xlink:href="xsd:anyURI" />
    <t2sr:properties>
        <t2sr:property t2sr:name="xsd:string"
                xlink:href="xsd:anyURI" /> *
    </t2sr:properties>
</t2sr:listenerDescription>
 200
/configuration GET Retrieves a string holding the (non-modifiable) configuration of this listener.

Result format:

xsd:string
 200
/properties GET Retrieves a listing of the modifiable properties of this listener (as XML or JSON).

Result format:

<t2sr:properties>
    <t2sr:property t2sr:name="xsd:string"
            xlink:href="xsd:anyURI" /> *
</t2sr:properties>
 200
/properties/{name} GET Retrieves the string that is the value of the named property.

Result format:

xsd:string
 200
PUT Sets the named property to the provided string value, and returns the new current value of the property.

Input/result format:

xsd:string
 200, 403

The current implementation does not permit installing new listeners, and comes with a single listener called io which provides the stdout, stderr and exitcode properties, all of which do not permit update. This means that the standard output of the workflow run is available at /runs/{uuid}/listeners/io/properties/stdout.

  • EPSRC
  • BBSRC
  • ESRC
  • EU FP7
  • JISC
Hosted at the School of Computer Science, University of Manchester, UK.
Legal stuff | Contact us