Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current ·  View Page History

There are two main types of web-services: REST (REpresentational State Transfer) and WSDL (Web Services Description Language) /SOAP.

REST services

REST services use the HTTP protocol. As described on wikipedia, a common mapping of services is:

Resource

GET

PUT

POST

DELETE

Collection URI, such as http://example.com/resources/

List the URIs and perhaps other details of the collection's members.

Replace the entire collection with another collection.

Create a new entry in the collection. The new entry's URL is assigned automatically and is usually returned by the operation.

Delete the entire collection.

Element URI, such as http://example.com/resources/item17

Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type.

Replace the addressed member of the collection, or if it doesn't exist, create it.

Treat the addressed member as a collection in its own right and create a new entry in it.

Delete the addressed member of the collection.

POST is also commonly used as a means of performing a complex get or search operation. The POSTed data specifies the parameters to the search

Tools to build REST services

The Java API for XML Web Services (JAX-WS) provides full support for building and deploying REST Web services. It is tightly integrated with the Java Architecture for XML Binding (JAXB) for binding XML to Java data and is included in Java 6.

Some guidelines on building REST Web services can be found online.

WSDL/SOAP Web services

Web Service Description Language (WSDL) Web services operate by exchanging Simple Object Access Protocol (SOAP) messages with clients over HTTP.

WSDL Web services are defined by their WSDL document, an XML format that represents an interface to a Web service. WSDL is machine-readable description of the operations (functions) and parameters offered by the service, i.e. XML message types that the service receives and produces and that get wrapped in SOAP messages exchanged between the client and the service.

WSDL binding describes how a particular Web service is bound to the underlying SOAP messaging protocol (or any other protocol used as a carrier). A WSDL-SOAP binding can be either a Remote Procedure Call (RPC)-style binding or a document-style binding. A SOAP binding can also have an encoded use or a literal use. This gives four style/use models:

  • RPC/encoded
  • RPC/literal
  • Document/encoded
  • Document/literal

There is also a fifth binding style that is commonly referred to as the document/literal wrapped. Thus, developers have five binding styles to choose from when creating a WSDL file. A good description of the differences between these styles can be found online.

Common service creation mistakes

"Press a button" service publishing

It is very easy to think that providing a service can be done by simply running a tool over existing code. This may "tick the box" of making a service available, but the service is likely to be almost unusable by service consumers. When generating a service, it is necessary to think about what the service consumer needs. The best way to do this is to create the services "contract first" i.e. design the service's WSDL or REST and associated document formats, then from those generate the classes and methods for the service; the service methods are then implemented by calls to the existing code. Alternatively (and more commonly) the existing code should be wrapped and annotated so that consumer-oriented services are generated.

Assumption of knowledge

It is easy for the service provider to assume that service consumers will know almost as much about the service as they do. This assumption leads to lack of documentation, strange features (parameters that change meaning or that should not be used together), changes in the semantics of output and input data.

The service provider should assume that the service consumer's knowledge of the service is minimal. The service consumer merely wants to achieve the task exposed via the service.

Lack of documentation

Many services are poorly described. Even when the services are registered with, for example, the BioCatalogue, only minimal effort is put into documenting them. An undocumented service is an unusable service. The documentation should include, at least,

  • description of the task that the service performs - what it does from a service consumer's point of view
  • what can be used as input, with example values and description of what happens if the value is not specified
  • what will be returned as output, including example values
  • possible error messages, including what they mean from the point of view of the input data and the intended task. The error message should not be described by relation to what has gone wrong in the provider's code

It is very useful if the documentation includes:

  • example workflows that use the service
  • other services that work well with the service

Wrong granularity

Services should expose consumer-oriented tasks i.e. what a service consumer wants to do. Services should not expose provider-implemented operations i.e. what the service provider's code does to perform a task.

If the service that is being exposed corresponds to methods or functions within the service provider's code then the service consumer must use in a specific order to achieve a task.

Exposure of implementation data

The internal details of the service implementation should be hidden, as far as possible. For example, just returning a serialization of a Java object is not a sensible or usable response to a service call.

The exposure of even internal ids can cause problems as the services may assume that an internal id is passed in. How is the service consumer meant to know the id?

Wherever possible, implementation classes, data and ids should not be exposed by the service. The service provider should look at what is actually returned by some example service calls and consider if they are actually usable.

Do not return HTML unless it is HTML data

REST GET services are very similar to fetching pages for a web browser. Some service providers simply deliver an HTML document corresponding to what they would return when the corresponding web page is fetched.

Unless the service is requesting a HTML document, the service provider should not return an HTML document. The service should probably return the data that underlies the HTML document.

Because it is possible to use web-content providers as if they are REST services, it is possible that apparent REST services within a workflow will actually be fetching HTML documents. Wherever possible it should be made clear that it is not a "proper" REST service.

Do not specify the format as a parameter of a REST service

The HTTP protocol used by REST has a mechanism for specifying in the message header the format that the data should be returned in. For example:

REST services should not specify the format as part of the URL or message body e.g.

Such a resource should be requested from http://www.example.com with Accept header application/xml.

The use of a format parameter can cause problems. For example, if the service consumer requests "http://www.example.com/fred?format=xml" with "Accept: application/json" then it should be impossible for the transaction to take place.

Labels
  • None