Skip to end of metadata
Go to start of metadata

REST services

REST stands for REpresentational State Transfer. REST services operate over HTTP and typically expose some of the following four types of operations:

  • GET - to get a resource
  • POST - to make a new resource or to perform a request (such as search)
  • PUT - to update a resource
  • DELETE - to delete a resource

Taverna supports invoking services via all four of the above operations; based on the chosen operation users can configure different parameters.

Operation

Inputs

Outputs

Configuration parameters

GET

URL input parameters

response body, status code, redirection

URL signature, HTTP headers (such as Accept, etc.)

PUT

URL input parameters, request body

response body, status code, redirection

URL signature, HTTP headers (such as Accept, Content-Type, etc.)

POST

URL input parameters, request body

response body, status code, redirection

URL signature, HTTP headers (such as Accept, Content-Type, etc.)

DELETE

URL input parameters

response body, status code, redirection

URL signature, HTTP headers (such as Accept, etc.)

URL input parameters are used by Taverna to generate service input ports dynamically at the time of the service configuration. During configuration, the service URL signature is defined using a standard notation that indicates the parameters that distinguish the resource, and what we want to know about the resource and any filters, e.g.

The elements surrounded by {} are URL input parameters and will be used generate input ports for the service named after the parameter. Parameters will be replaced with the data present at those ports at the time of execution. Taverna will URL-encode data used for URL parameters by default; they can also be sent as they arrive without any encoding.

Various HTTP headers can also be configured. The most notable ones are the Accept header (for all four operations), and the Content-Type (for PUT and POST only).

It is also possible to define a value for any other standard HTTP header and to add service-specific ones. Taverna will simply include the header name and value as is when doing the HTTP request and will not perform any action based on the headers being set. This means that, for example, there is not point in setting Content-MD5 header unless you calculate the MD5 digest of the message yourself and set the value of the header to contain the digest as Taverna will not do it for you.

The output of all four operations is the response body, as returned by the service. If the Content-Type returned by the service is of text/... form, Taverna will treat it as a string and will look for charset parameter in the Content-Type header. If there is not one, it  will try to decode the text using UTF-8 encoding. For any other Content-Type,  for example application/..., Taverna will treat it as binary data.

Request message body, used for POST and PUT operations, is sent as is. If a service expects some special encoding of the data then it is up to the workflow creator to make sure that the data is properly formatted before it is passed to the REST service.

There is also a status output port that reports the HTTP status code returned by the service - common codes being 200, 301, 302, 303, 401, 404, 500. For a full list of HTTP status codes, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

In the case the service uses redirection (or a chain of redirection), the final redirection URL and its response code is provided back through the output port of the service. In the case that there is no redirection, the redirection output is left empty.

GET

Configured using a URL signature as described above, and optionally with the Accept header (the MIME type for the representation of the resource), and any other HTTP header the user may wish to configure.

Returns the body of the response, the final status code, and final redirection if applicable.

PUT

Configured using a URL signature as described above, and optionally with both the Content-Type (of the message being sent to the service), and the Accept header for the representation of result. Other HTTP headers may be included as well.

Can take either the body representing the resource (according to the Content-Type), values as parameters, or a combination of both.

Returns the body of the response, the final status code, and final redirection if applicable.

POST

Same as PUT.

DELETE

Configured using a URL signature as described above.

The Accepts header attribute can be configured to determine the representation of the resulting response body (if there is one).

WSDL services

Taverna aims to support Web services that are compliant with Web Services Interoperability (WS-I) standard. This is a long-term goal and currently there are a few nuances. However, it is possible to create WSDL Web services that are compatible with Taverna if you follow certain guidelines.

Although Taverna supports bindings that are RPC/encoded and RPC/literal to a fair extent, the preferred binding style is document/literal wrapped, i.e. the WSDL should have “style” attributes that are set to “document” and “use” attributes set to “literal”. This is particularly the case when dealing with complex types; for primitive types no problems are anticipated.

Currently not tested

The following are not tested, and although not proven to fail, the behaviour is currently undefined. For this reason it is advised that the use of the following features is avoided.

  • Multiple WSDL imports. Taverna has only been tested on services that contain either no, or only one import of an additional WSDL file. For WSDLs that import more than one additional WSDL document, particularly if that WSDL has a different service endpoint to the others, the behaviour of Taverna is currently unclear. It is expected that it will fail when invoking the Web service. This does not affect imports of XML schema - this has been thoroughly tested and works as expected as long as schemas are publicly available.
  • Multiple service endpoints. For a given WSDL Taverna currently only references the first service endpoint. If more than one exists then operations belonging to the second endpoint are expected to fail.
  • Ambiguous type names. In the unusual case when an operation requires inputs that contain identically named types that belong to different namespaces it is expected that Taverna should not have any problems. However, because of the unusual nature of this it is untested and therefore not recommended.

Currently not working

The following are known to fail in Taverna and should be avoided.

  • Cyclic references. When processing the result of invoking an operation, Taverna resolves the XML into a single document. If the response contains cyclic references, this is detected and an error occurs (to prevent an infinitely long document). For this reason cyclic references should be avoided. (Taverna will, however, work with such an operation as long as the cyclic reference is not contained within the response data structure).
  • Overloaded operations. For a given service, Taverna distinguishes between its operations only by name. The operation signature is not used to distinguish between operations of the same name. For this simple reason, Taverna does not support overloaded operations.
  • xsd:anyType. xsd:anyType type can be used to represent a parameter that can be of any type. Although Taverna can invoke a service that deals with the anyType type, the XML splitting mechanism for the message to be sent/received cannot work since there is no information about the data structure required or received. Such services can only be used by providing and/or manipulating the XML directly inside the workflow.
  • Sending SOAP messages with attachments. This refers to the method of using Web Services to send and receive files as SOAP message attachments. Since the fact that a service can accept an attachment is not described in a WSDL document – Taverna cannot know this and therefore does not support it. However, if a service returns attachments (there can be more than one) – Taverna can extract them and returns them on a special service output port called attachmentList.

Since the use of the use of SOAP attachments to pass data is not supported in Taverna and SOAP attachments are not practical for passing large files anyway, it is advised to pass files per references only and then upload the file inside the service. 

Labels
  • None