Posted by a.pawlik on 4 December 2013 - 9:30am 

By Alex Nenadic, Alan Williams, Robert Haines and Alasdair Gray of MyGrid, Anton Güntsch of the Freie Universität Berlin, and Aleksandra Pawlik of the Software Sustainability Institute.

You have a piece of data-processing code, it works well, and both your colleagues and other researchers think it is useful. So, you decide to turn it into a Web Service so that it can be used by anyone with Web access. Yet do you know how to go about it? These Top Tips will help you get started.

Do not “press a button” on existing code

Creating a Web Service should not be a box-ticking exercise. It is very easy to think that providing a service can be done by running a tool over existing code. Web Services are nearly always implemented as an afterthought. As a rule, service providers usually have some local code and an interface that they set aside as a public service. Sadly, the interface often ends up being cumbersome and hard to use and understand, tied, as it is, to the underlying local implementation and configuration, exposing internal ids, class names and formats. So use your own systems and workflows instead, rather than local APIs.

Think about the service users

If your code is already in use, think about those who are using it. What are their needs? How do they use it? What are their skills? This should be a starting point for the design. If you want to make a useful service, you need to accommodate users’ needs. In general, assume that the service consumer’s knowledge is minimal. The service consumer merely wants to achieve the task exposed the service assists them with.

Design your services with compatibility and interoperability in mind

More than 70% of the steps in a workflow convert data from one format to the other and less than 30% do any science with that information. If there is a data compliance model in your service domain then you should consider coding against it. There are a few service initiatives to try to define data exchange formats and service ontologies, such as BioXSD Data Exchange Format, BioSharing, VO Table interchange format and others. You also need to make sure that your service fails gracefully. If something does go wrong, the workflow should not crash and still be able to operate, even if the final output will be an error message, preferably constructed in such a way that helps the user find a solution.

Stick to standards

There are a number of standards for services in particular domains, such as BioCASE, Web Map Service and the IVOA services . If your service is in a domain with these standards, then it is a good idea for you follow them. Most of these standards use similar concepts such as the requirement to provide a capabilities document that describes the particular data or algorithms used. These documents often include a description and summary of any potential errors. It is a good idea to deliver a capabilities document even if you do not implement against a standard. If there is no current standard for your domain/service, consider creating a group to develop such a standard. It will make the life of service consumers so much easier and will ease the adoption of Web Services in your domain. Meanwhile, if service returns data for which well-defined vocabularies exist, such as ISO country names and ISO languages, then use them and document their use. Client systems will then be able to easily integrate service using the same vocabularies.

However, there is one caveat in following these standards. The service may then become too difficult to use for any “external” users who are not familiar with its standards. So consider adding simplified streamlined access points to help outside users too.

Keep it simple

Preferably, a service should only do one thing. Polymorphism occurs when the task performed by the service is determined by one of the parameters to the service call. For a polymorphic service, the validity, meaning or permitted values for other parameters may depend upon the value of the controlling parameter. This can cause confusion and increases the likelihood that users will make bad or nonsensical requests of the service. In short, polymorphic services are bad practice and so strongly discouraged.

Never expose implementation details

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 internal IDs can also cause very obvious problems. Wherever possible, then, implementation classes, data and IDs should not be exposed by the service. The provider should furthermore look at what is returned by some example service calls and consider if they are in fact usable.

Have a maintenance and sustainability plan

Users value services that are reliable and stable but these decay over time if they are not maintained properly. Reliability and stability increase users' confidence in your services. With that in mind, the development of a maintenance and sustainability plan is a good idea.

You may also consider hosting your services on a cloud. The advantage of this solution is that it provides greater reliability, stability and capacity for users in comparison to services run on a desktop PC under someone's desk. The disadvantage is that you have to pay for it and once you stop, your service does too.

Take advantage of others’ knowledge and experience

Sometimes you don’t have the answers, but there is a good chance there is someone out there who can answer these questions for you. Ideally, this might be a domain expert who has created services which are now widely used.

Document your service

The documentation should include, at the very least, a description of the task that the service performs and what it does from a service consumer's point of view. Also, what can be used as input, with example values and a description of what happens if the value is not specified, and what will be returned as output, including example values. Just as important is listing any 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 simply be described in relation to what has gone wrong in the provider's code

It is also very useful if the documentation includes example programs, scripts and/or workflows (including example input data and results) that use the service and a list of other services that work well with the service.

Register your service in a service catalogue

Unless you intend to keep your service private, it is very good practice to register it. There are a number of service registries. Some of them, such as seekda, are general and can be used for any WSDL service. Other registries are domain-specific, such as the BioCatalogue for Life Science Web Services,  the BiodiversityCatalogue which is  a curated catalogue of Biodiversity Web Services or one of the registries of the International Virtual Observatory Alliance (IVOA) for archives of Astronomical data.