Skip to end of metadata
Go to start of metadata

This document describes a quick and simple approach to getting some basic REST support within T2. Its not an attempt at a perfect solution, emcompassing WSDL2 and WADL - but a basic approach as a starting point which may actually be implemented, and can have WSDL2 and WADL support added incrementally.
Its been updated to reflect discussion with users, here are the slides that were used in that discussion: Rest-Strawman.ppt

Jira tasks

Separate Jira tasks have been created.

Services

REST is based upon 4 basic HTTP operations, and in T2 we need 4 different Services that represent these operations. There is some debate whether there could be 1 single Service that is configured to perform a particular operation, but I prefer 4 seperate services as it is simpler to configure and makes choosing an operation a more explicit decision whilst building the workflow. (agreed in User discussion).

Each Service can be an extension of an abstract super-class that contains the common functionality.

Operation

inputs

outputs

config params

purpose

GET

parameter inputs

response body, status, redirection

url signature, accepts

fetch data

PUT

parameter inputs, request body

response body, status, redirection

url signature, accepts, content_type

update data

POST

parameter inputs, request body

response body, status, redirection

url signature, accepts, content_type

create data

DELETE

parameter inputs

response body, status, redirection

url signature, accepts

delete data

Parameter inputs are generated dynamically during a configuration phase, when the Service is first created. During configuration a URL signature is presented 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 {} indicate that they are parameters and will therefore generate input ports, and be replaces with the data (URI encoded) presented at those ports. This is compatible with BioCatalogue. A current difference is that the parameter name is the item within the {} also for query arguments, although BioCatalogue has decided to make a change to follow the same rule.

(The pattern above in BioCatalogue would create an input parameter title with a default value of name, while this suggestion is that {name} would always create a parameter called name - allowing the user to give more explicit input port names, say ?db={database})

The Accepts header, and for PUT and POST the Content type, is also a configuration option and determines the representation of the resource, generally either application/xml or application/json. We should have a pre-defined list of these as a drop-down option, but also allow for users to define their own as free text.

The output is the response body, which will generally be either an XML or JSON document. There is also a status output that reports the HTTP status code - common codes being 200, 301, 302, 303, 401, 404, 500. For a full list of http status codes visit: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

GET

Configured using a URL signature as described above, along with the Accepts setting (the mime type for the representation of the resource).

Returns the body of the response, the final status code, and final redirection if applicable (see below for more details about redirection).

PUT

Configured using a URL signature as described above, along with both the ContentType (of the stuff being pushed up), and the Accepts setting for the representation of result.

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

Returns the body of the response, the final status code, and final redirection if applicable (see below for more details about redirection).

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).

XML & JSON

With the absence of a WADL or WSDL2, the user will largely be responsible for handling the resulting, and generation, of XML. 

For the handling of the results an updated version of the current XPath handler would be sufficient. This can be enhanced to make it easier to configure. A suggestion from our Users was to be able to present (copy & paste) some example XML, which is then presented as a Tree from which the required XPath is selected by selecting a node in the tree.

Generating XML inputs can be achieved by providing a templating mechanism. There is an exercise required in assessing current templating tools (such as Apache Velocity), or whether we can provide an example beanshell script. It would work along the lines of:

where #{} elements are replaced by inputs of the same name - taking care to handle inserted XML, or other strings that could break the XML, with CDATA elements.

JSON can be handled similarly, and there is a JSONPathproject worth looking at. JSON support was concidered a low priority by our Users.

As a first version, the XML handling would be handled external to the Rest activity, but in the future having this support embedded within the activity is highly desirable so as to prevent the XML Splitter shim problem.

Redirects

Following on from discussions with Users, exposure to redirection should be kept to a minimum. If there is a chain of redirection, only the final redirection URL, and its response code is provided back through the output port. In the case that there is no redirection, the redirection output is left empty.

Authorization

Authorization, for example HTTP basic auth, should be configured using the Credential Manager as with any other service type. This won't require any specific changes or requirements within the Service implementation as long as it uses standard http java libraries (its not expected to work with Apache commons http-client libraries without additional work).

Priorities

A rough prioritised list based upon feedback within the meeting with Users

HIGH

  • GET
  • PUT
  • POST

MEDIUM

  • XPath enhancements
  • XML templates
  • DELETE

LOW

  • JSON
  • Embedded XPath support
Labels
  • None