Taverna 2 Server: API of the REST Interface

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/permittedListenerTypes 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).
Operating
The 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.