Minimum Information about the Operation of a Web Service (MIAOWS)

Author List

Introduction

The use of Web Services in bioinformatics research is still in its infancy. After some initially enthusiastic optimism [6], and early success stories [7] [8] [9] [10] much of the promise of Web Services technology for use in biological and biomedical investigations is yet to be realised.

One of the biggest barriers to adoption is that users are frequently unable to find services [11], and operate them [12], due to the lack basic service metadata available from a centralised service registry.

There are many different definitions of what a Web Service is, and this has led to much confusion as to how many services exist, what their capabilities are and how they should be described. The W3C describes a Web Service as "a software system designed to support interoperable Machine to Machine interaction over a network." For the purposes of this document, a web service is defined as follows:

A Web Service is a function identified by a URI [13] which accepts at least one input and produces at least one output using HTTP [14].

1. Form-style services, typically HTML forms.
2. RESTful Web Services [15]
3. SOAP Web Services [16].

For the purposes of this abstract specification, the differences between these styles of service are not crucial, as we wish to capture an abstract description of the minimum information required to operate the service, regardless of the services interface.

This document represents the minimum information that should be reported about a Web Service to allow a reader to interpret and critically evaluate the operation and information produced from the implementation of the serivce to support their experimental corroboration. In practice the MIAOWS document comprises a checklist of information that should be provided or ascribed to a Web Service upon publication. The MIAOWS modules specify neither the format that data should be transferred in, nor the structure of the repository. In this respect a MIAOWS module is implementation independent definition of a particular technology and follows the design principles and presentation format of the MIAPE guidelines [17].

The information defined within this document should facilitate the interpretation, dissemination and evaluation of the operations of a Web Service. The MIAOWS reporting guidelines define the minimum information that should be associated with a published Web Service, primarily to operate, as opposed to find a Web Service. Defining the minimum information required to find a web service is a complex and context dependent issue, which is outside the scope of this document [18] [19] [20]. However, we recognised that the MIAOWS metadata can be utilised as a method to find a service in a particular registry; basic operational data is the first step towards helping users find services.

The reporting requirements contained within this document should comply with two general criteria; as outlined in Taylor et al, 2007 [17];

• Sufficiency. The MIAOWS reporting requirements should require sufficient information about a Web Service and its operational context to allow a reader to understand and critically evaluate the application and the results produced, and to support their experimental corroboration.
• Practicability. Achieving MIAOWS compliance should not be so burdensome as to prohibit Web Serivce publication or operation.

The MIAOWS reporting guidelines define the necessary but not sufficient information to allow discovery of arbitrary services by agents, such as humans or Conforming and ascribing MIAOWS metadata to Web Serivces will benefit the life-science research community, whether as service providers, curators or users and help to realise the potential of Web Services for processing life-science information. Specifically, defining what the service is, the operation it is designed to perform, the input parameters and the resulting output.

The following section, detailing the reporting requirements for the operation of a Web Service, is subdivided as follows:

1. Service
2. Operation
3. Input Parameters
4. Output

The glossary table provides a definition for each checklist item in the MIAOWS guidelines. Examples are given only to facilitate interpretation and are not intended to be a comprehensive list of the technologies that can or cannot be recorded under each section heading.

In this document the key words "MUST", ''MUST NOT", "REQUIRED'', "SHALL",  "SHALL NOT'', "SHOULD'', "SHOULD NOT'', "RECOMMENDED'', "MAY", and "OPTIONAL'' are to be interpreted as described in RFC-2119 [21].

Reporting requirement for the operation of a Web Service

1. Service

1. Name
   
2. Version
3. Service style
   

2. Operation

1. Name
2. Objective

3. Input parameters

1. Name
2. Data type
3. Data constraint
   
4. Required parameter

4. Output

1. Data type
2. Data constraint
   

Related Work

There are several existing projects that have attempted to describe web services, especially those used in biology, in different ways. A complete comparison between these systems is out of scope for this document. Instead, we describe abstractly what the minimum information required is to operate a service, rather than how it is described. To the best of our knowledge, no other projects have specified this separately from examples of how services are described in practice.

Summary

The MIAOWS reporting requirements for the operation of a Web Service specify that a significant degree of detail be captured about the service, the parameters and the output. These guidelines will evolve.

Tables

Table 1 - MIAOWS Glossary of required items