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 aworkflow 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 |
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 needsto be manually moved back into * |
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 |
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 gets a file contents (only forfiles), asking for application/xml or application/json does a listing (only for directories), and asking for 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 |
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 |
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 |
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 filesetting. 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 |
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 workingdirectory. 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
.