Skip to end of metadata
Go to start of metadata

This document does not necessarily include a complete summary of the REST API of Taverna Server 2.5; some resources and some content types may be missing from this document. The WADL document for the server gives a definitive description of the resources and the XML for the documents consumed and produced by those resources; the JSON is mechanically related to the XML.

API of the Taverna Server REST Interface

The 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:

 

To be exact, a suffix of “*” marks an element that can be repeated arbitrarily often, a suffix of “?” marks an element or attribute that can be either present or absent, and otherwise exactly one of the element is required (or, for attributes, the attribute must be present). 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/

port

http://ns.taverna.org.uk/2010/port/

xlink

http://www.w3.org/1999/xlink

xsd

http://www.w3.org/2001/XMLSchema

Main Server Resource

Resource: /

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Retrieves a description of the server as either XML or JSON (determined by content negotiation) that indicates other locations to find sub-resources.

 

The feed element is a pointer to the location of the Atom feed for events issued to the user about things like the termination of their workflows.

Resource: /runs

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Retrieve a list of all runs that the current user can see, as XML or JSON. Note that the user will not be told about runs that they are not permitted to see (i.e., that they didn’t create and haven’t been given permission to see). Deleted runs will also not be present.

 

 

Method: POST
Consumes: application/vnd.taverna.t2flow+xml, application/xml
Produces: text/plain
Response codes: 201 Created

Accepts (or not) a request to create a new run executing the given workflow. The content should normally be a t2flow workflow document with the t2flow content type, but when the content type is plain XML, the workflow must be wrapped (in an XML infoset sense) inside an {http://ns.taverna.org.uk/2010/xml/server/}workflow element.

 

The result will be a redirect (via Location: HTML header) to the resource created for this particular run; the body of the response will be empty, or a string describing exactly why the run creation is taking some time. Total failure will be reported by an HTTP error. The run will be in the Initialized state, with a default lifetime.

Resource: /policy

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Describe the (public) parts of the policies of this server, as XML or JSON.

 

 

Resource: /policy/capabilities

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Gets the list of supported capabilities of the execution engine. This list is a collection of URIs that describe the abstract capabilities, together with a version associated with each of them.

Resource: /policy/enabledNotificationFabrics

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Gets the list of supported, enabled notification fabrics. Each corresponds (approximately) to a protocol, e.g., email.

Resource: /policy/permittedListenerTypes

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Gets the list of permitted event listener types.

Resource: /policy/permittedWorkflows

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: not secured

Gets the list of permitted workflows. An empty list indicates that all workflows are permitted.

Resource: /policy/runLimit

Method: GET
Consumes: N/A
Produces: text/plain (xsd:int)
Response codes: 200 OK
Notes: not secured

Gets the maximum number of simultaneous runs that the user may create. Note that this is an upper bound; other resource contention may cause the actual number to be lower.

Per-Workflow Run Resource

Note that all of these resources require that the user be authenticated and permitted to (at least) see the run.

Resource: /runs/{id}

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Describes the sub-resources associated with this workflow run, as XML or JSON.

 

 

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No Content
Notes: requires Destroy permission

Deletes a workflow run, cleaning up all resources associated with that run.

Resource: /runs/{id}/expiry

Method: GET
Consumes: N/A
Produces: text/plain (xsd:dateTime)
Response codes: 200 OK

Gives the time when the workflow run becomes eligible for automatic deletion.

Method: PUT
Consumes: text/plain (xsd:dateTime)
Produces: text/plain (xsd:dateTime)
Response codes: 200 OK
Notes: requires Destroy permission

Sets the time when the workflow run becomes eligible for automatic deletion. Note that the deletion does not necessarily happen at exactly that time; that depends on the internal mechanisms of the server.

Resource: /runs/{id}/createTime

Method: GET
Consumes: N/A
Produces: text/plain (xsd:dateTime)
Response codes: 200 OK

Gives the time when the workflow run was first submitted to the server.

Resource: /runs/{id}/finishTime

Method: GET
Consumes: N/A
Produces: text/plain (xsd:dateTime or empty)
Response codes: 200 OK

Gives the time when the workflow run was detected as having finished executing, or the empty string if the workflow run has not yet finished.

Resource: /runs/{id}/startTime

Method: GET
Consumes: N/A
Produces: text/plain (xsd:dateTime or empty)
Response codes: 200 OK

Gives the time when the workflow run was started, or the empty string if the workflow run has not yet been started.

Resource: /runs/{id}/status

Method: GET
Consumes: N/A
Produces: text/plain (“Initialized” or “Operating” or “Stopped” or “Finished”)
Response codes: 200 OK

Gives the current status of the workflow run. Note that the “Stopped” state is not currently used.

Method: PUT
Consumes: text/plain (“Initialized” or “Operating” or “Stopped” or “Finished”)
Produces: text/plain (“Initialized” or “Operating” or “Stopped” or “Finished”)
Response codes: 200 OK

Attempts to update the status of the workflow run. This is the only mechanism for setting a workflow run operating, and an operating run can be cancelled by forcing it into the finished state.

Resource: /runs/{id}/workflow

Method: GET
Consumes: N/A
Produces: application/vnd.taverna.t2flow+xml, application/xml, application/json
Response codes: 200 OK

Gives the workflow document used to create the workflow run, as raw t2flow, wrapped XML or wrapped JSON. (Note that the last is not supported for re-upload.)

Resource: /runs/{id}/input

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Describe the sub-URIs relating to workflow inputs.

 

 

Resource: /runs/{id}/input/baclava

Method: GET
Consumes: N/A
Produces: text/plain
Response codes: 200 OK

Gives the Baclava file describing the inputs, or empty if individual files are used. The name is relative to the main working directory. Use of a Baclava input file will inhibit the generation of a run bundle.

Method: PUT
Consumes: text/plain
Produces: text/plain
Response codes: 200 OK

Sets the Baclava file describing the inputs. The name is relative to the main working directory, and must not be empty. Use of a Baclava input file will inhibit the generation of a run bundle.

Resource: /runs/{id}/input/expected

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Describe the expected inputs of this workflow run. They must be supplied by either per-input specifications or by the baclava file.

 

 

Resource: /runs/{id}/input/input/{name}

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a description of what is used to supply a particular input, which will be either a literal value or the name of a file in the working directory or a reference to a file maintained by another workflow run on the same server (which will be copied efficiently if the user has permission). The listDelimiter attribute, if present, is a single character used to split the value (whether a literal or soured from a file) into a Taverna list.

 

 

Method: PUT
Consumes: application/xml, application/json
Produces: application/xml, application/json
Response codes: 200 OK

Sets the source for a particular input port (and cancels any use of baclava to supply that port). The document format for both the consumption and production side of this operation is as above.

Resource: /runs/{id}/output

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a description of the outputs (in XML or JSON) as currently understood. Note that only very limited understanding of the outputs will be present before the workflow is run; the majority of information is generated during the execution of the run.

 

 

Method: GET
Consumes: N/A
Produces: text/plain
Response codes: 200 OK

Gives the Baclava file where output will be written (relative to the working directory); empty means use multiple simple files in the out directory. Use of a Baclava output file will inhibit the generation of a run bundle.

Method: PUT
Consumes: text/plain
Produces: text/plain
Response codes: 200 OK

Sets the Baclava file where output will be written (relative to the working directory); empty means use multiple simple files (in a directory structure where lists of lists are involved) in the out directory. Use of a Baclava output file will inhibit the generation of a run bundle.

Resource: /runs/{id}/generate-provenance

Method: GET
Consumes: N/A
Produces:  text/plain (boolean: “true” or “false”)
Response codes: 200 OK

Get whether provenance (i.e., a run bundle) will be created for the workflow run. This defaults to false.

Method: PUT
Consumes: text/plain (boolean: “true” or “false”)
Produces:  text/plain (boolean)
Response codes: 200 OK

Set whether provenance (i.e., a run bundle) will be created for the workflow run, returning the current value. This is only meaningful if set before setting the workflow status to Operating and has no effect otherwise.

Resource: /runs/{id}/run-bundle

Method: GET
Consumes: N/A
Produces:  application/vnd.wf4ever.robundle+zip
Response codes: 200 OK, 404 Not Found

Get the run bundle for the workflow run. This is not guaranteed to exist until after the workflow run finishes, if generation of it was explicitly requested (see /runs/{id}/generate-provenance above), and directing outputs to go to a Baclava file will prevent the generation of a run bundle at all.

Resource: /runs/{id}/stdout

Method: GET
Consumes: N/A
Produces:  text/plain
Response codes: 200 OK

Get the standard output from the execution engine used during the workflow’s running. This is empty before the workflow run starts.

Resource: /runs/{id}/stderr

Method: GET
Consumes: N/A
Produces:  text/plain
Response codes: 200 OK

Get the standard error from the execution engine used during the workflow’s running. This is empty before the workflow run starts.

Resource: /runs/{id}/log

Method: GET
Consumes: N/A
Produces:  text/plain
Response codes: 200 OK

Get the content of the execution engine’s log file. This is empty before the workflow run starts.

Resource: /runs/{id}/usage

Method: GET
Consumes: N/A
Produces:  application/xml
Response codes: 200 OK, 204 No content

Get a description of the resources used during the running of the workflow in Usage Record 1.0 format. Before the workflow finishes, this is empty and results in a “204 No content” response code being used instead of “200 OK”.

Resource: /runs/{id}/interaction

This is an ATOM feed of events generated from interaction activities in the workflow run.

Resource: /runs/{id}/listeners

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/{id}/lis­teners/io/prop­erties/stdout. (It is also surfaced as /runs/{id}/stdout from Taverna Server 2.5 onwards.)

Compatibility Note

The listener interfaces are likely to be removed entirely from a future version of Taverna Server; the structure of the functionality intended to be surfaced by them has evolved in a different way to what was originally expected.

 

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Get a list of the listeners installed in the workflow run.

 

 

Method: POST
Consumes: application/xml, application/json
Produces: N/A
Response codes: 201 Created
Notes: Identity of created listener provided through Location header in response.

Add a new event listener to the named workflow run of the given type and under the conditions imposed by the contents of the configuration document (the body of the element). Note that the configuration cannot be changed after creation.

 

 

Resource: /runs/{id}/listeners/{name}

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Get the description of a particular listener attached to a workflow run.

 

 

Resource: /runs/{id}/listeners/{name}/configuration

Method: GET
Consumes: N/A
Produces: text/plain
Response codes: 200 OK

Get the configuration document for the given event listener that is attached to a workflow run.

Resource: /runs/{id}/listeners/{name}/properties

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Get the list of properties supported by a given event listener attached to a workflow run.

 

 

Resource: /runs/{id}/listeners/{name}/properties/{propName}

Method: GET
Consumes: N/A
Produces: text/plain
Response codes: 200 OK

Get the value of the particular property of an event listener attached to a workflow run.

Method: PUT
Consumes: text/plain
Produces: text/plain
Response codes: 200 OK

Set the value of the particular property of an event listener attached to a workflow run.

Resource: /runs/{id}/security

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a description of the security information supported by the workflow run.

 

 

Resource: /runs/{id}/security/credentials

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a list of credentials supplied to this workflow run.

 

 

For more description of the contents of the userpass and keypair elements, see below.

Method: POST
Consumes: application/xml, application/json
Produces: N/A
Response codes: 201 Created
Notes: Identity of created credential is in Location header of response.

Creates a new credential. Multiple types supported. Note that none of these should have their xlink:href attributes set when they are POSTed; those will be supplied by the service. Take particular care with the serviceURI elements, which must define the URI as expected by the Taverna Credential Manager.

Password credential:

 

 

Key credential (note that one of the credentialFile and credentialBytes elements should be supplied, but not both):

 

 

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No content

Deletes all credentials.

Resource: /runs/{id}/security/credentials/{credID}

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Describes a particular credential. Will be one of the elements userpass, keypair and cagridproxy as outlined above.

Method: PUT
Consumes: application/xml, application/json
Produces: application/xml, application/json
Response codes: 200 OK

Updates (i.e., replaces) a particular credential. Will be one of the elements userpass, keypair and cagridproxy as outlined above.

Method: DELETE
Consumes: N/A
Produces: application/xml, application/json
Response codes: 204 No content

Deletes a particular credential.

Resource: /runs/{id}/security/owner

Method: GET
Consumes: N/A
Produces: text/plain
Response codes: 200 OK

Gives the identity of who owns the workflow run.

Resource: /runs/{id}/security/permissions

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a list of all non-default permissions associated with the enclosing workflow run. By default, nobody has any access at all except for the owner of the run.

 

 

Method: POST
Consumes: application/xml, application/json
Produces: N/A
Response codes: 201 Created
Notes: Identity of created permission is in Location header of response.

Creates a new assignment of permissions to a particular user.

 

 

Resource: /runs/{id}/security/permissions/{user}

Method: GET
Consumes: N/A
Produces: text/plain (one of: none, read, update, destroy)
Response codes: 200 OK

Describes the permission granted to a particular user.

Method: PUT
Consumes: text/plain (one of: none, read, update, destroy)
Produces: text/plain (one of: none, read, update, destroy)
Response codes: 200 OK

Updates the permissions granted to a particular user.

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No content

Deletes (by resetting to default, i.e., none) the permissions associated with a particular user.

Resource: /runs/{id}/security/trusts

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Gives a list of trusted identities supplied to this workflow run.

 

 

Method: POST
Consumes: application/xml, application/json
Produces: N/A
Response codes: 201 Created

Adds a new trusted identity. The xlink:href attribute of the trust element will be ignored if supplied, and one of certificateFile and certificateBytes should be supplied. The fileType can normally be omitted, as it is assumed to be X.509 by default (the only type seen in practice).

 

 

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No content

Deletes all trusted identities.

Resource: /runs/{id}/security/trusts/{trustID}

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK

Describes a particular trusted identity.

 

 

Method: PUT
Consumes: application/xml, application/json
Produces: application/xml, application/json
Response codes: 200 OK

Updates (i.e., replaces) a particular trusted identity. The xlink:href attribute will be ignored if supplied. The fileType can normally be omitted, as it is assumed to be X.509 by default (the only type seen in practice).

 

 

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No content

Deletes a particular trusted identity.

Resource: /runs/{id}/wd
Resource: /runs/{id}/wd/{path…}

Note that everything following the /wd is the path beneath the working directory of the workflow run; this is mapped onto the filesystem. An empty path is the same as talking about the working directory itself.

Be aware! Much of the selection between operations is done on the basis of the negotiated content type and the nature of the entity to which the path name matches.

Method: GET
Consumes: N/A
Produces: application/xml, application/json
Response codes: 200 OK
Notes: This only applies to directories.

Gives a description of the working directory or a named directory in or beneath the working directory of the workflow run. The contents of the dir and file elements are the equivalent pathname (for use in the SOAP interface or to be appended to …/wd to generate a URI).

 

 

Method: GET
Consumes: N/A
Produces: application/zip
Response codes: 200 OK
Notes: This only applies to directories.

Retrieves the contents of the given directory (including all its subdirectories) as a ZIP file.

Method: GET
Consumes: N/A
Produces: application/octet-stream, */*
Response codes: 200 OK
Notes: This only applies to files. Supports the Range header applied to bytes.

Retrieves the contents of a file. The actual content type retrieved will be that which is auto-detected, and the bytes delivered will be those that exist on the underlying disk file.

Method: PUT
Consumes: application/octet-stream
Produces: N/A
Response codes: 200 OK
Notes: This only applies to files.

Creates a file or replaces the contents of a file with the given bytes.

Method: POST
Consumes: application/xml, application/json
Produces: N/A
Response codes: 201 Created
Notes: This only applies to directories. The Location header says what was made.

Creates a directory in the filesystem beneath the working directory of the workflow run, or creates or updates a file's contents, where that file is in or below the working directory of a workflow run. The location that this is POSTed to determines what the parent directory of the created entity is, and the name attribute determines its name. The operation done depends on the element passed, which should be one of these:

 

 

Note that the upload operation is deprecated; directly PUTting the data is preferred, as that has no size restrictions.

Method: DELETE
Consumes: N/A
Produces: N/A
Response codes: 204 No content

Deletes a file or directory that is in or below the working directory of a workflow run. The working directory itself cannot be deleted (other than by destroying the whole run).

Labels
  • None