Abstract
In the early years of the VO, the SOAP Web Service paradigm was an important element of the IVOA Architecture. Developments around these services are more and more complex with an increasing number of standards (WS-*...). REST fielding00 is not a standard but a formalization of the URL use and it is easy to implement it. A service is RESTful if it follows a set of rules (which are not defined in a standard document). As there is no standard we think that it is necessary to define a minimal guideline about the “RESTfullness” in the VO context.
Status of this document
This is an IVOA Working Draft. The first release of this document was 2008 May 05.
This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than “work in progress”. A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
Acknowledgements
This document derives from discussions among the Grid and Web Services working group of the IVOA in Beijing (May 2007), Cambridge (September 2007) and Trieste (May 2008).
Note on conformance
Text within the following document is classified as either
normative
or informative
.
Normative text means information that is required to implement the Recommendation; an implementation of this Recommendation is conformant if it abides by all the prescriptions contained in normative text. Informative text is information provided to clarify or illustrate a requirement but which is not required for conformance.
The sections and subsections of this Recommendation are labeled, after the section heading, to specify whether they are normative or informative. If a subsection is not labeled, it has the same normativity as its parent section. References are normative if they are referred to within normative text.
Within normative sections, the key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in std:rfc2119.
Introduction
REST (Representational State Transfer) fielding00 is not a standard but a formalization of the URL use. It was introduced in 2000 in Roy Fielding’s Ph.D thesis fielding00. It refers to a set of network architecture principles which describe how to define and address resources. There is no REST fielding00 standardization process and the term “REST” is often used when the service is not based on standards like SOAP.
A service is RESTful if it follows a small set of rules (which are not defined in a standard document). As there is no standard we think that it is necessary to define a minimal guideline about the “RESTfullness” in the VO context.
Resource Oriented Architecture
A resource Oriented Architecture can be resumed to 4 concepts (resources, theirs names (URIs), their representation, the links between them) and 4 properties (addressability, statelessness, connectedness, uniform interface).
Representational State Transfer
Quick definition of REST and RESTful
In the REST approach, it may be sufficient to know the URI to access to a resource.
Examples:
In these examples it is possible to access to the information through a simple URL without the use of a specific tool (for C#, Java, Perl, ...) on the client side, the client has just to read simply the URL. In example 1) the URL returns the number of available pictures for m31 and in example 2) the URL returns the first picture.
Main feature of a REST service, from richardson07:
To be RESTful a service must be compliant with the following principles:
Quick comparison with SOAP services
If we take again the two previous examples of REST fielding00 URLs,
In SOAP we will have to define something like int getPictures (String object) for 1) and to use for example the SOAP with an attachment mechanism or to return the URL of the image for 2).
SOAP Web Service engines are also evolving by implementing the REST fielding00 alternative. For example, in Axis 2 it is possible for a client to specify that he want to access the service following the REST fielding00 paradigm.
How to describe a service?
WSDL (Web Services Description Language) booth07 has been created to describe SOAP services. These services are self-described by interrogation of the service endpoint URL with an extension like “?wsdl”. It is very difficult to use a SOAP Web Service without this description like when you try to use a Java API without the corresponding Javadoc. For REST fielding00, there is no standard way like WSDL booth07 but it is possible to use for example WADL (Web Application Description Language) wadl. RESTful services have simpler interfaces and the description is not as important as for SOAP WS. But in the case of automatic creation or use of the services by tools it is necessary to provide a description of the services. If a WADL wadl description is available it is then possible to generate for example the Java client code to query the service.
WADL
WADL (Web Application Description Language) wadl is a draft specification for an analogue to the WSDL language, specialised to RESTful interfaces.
The WADL distribution includes an XML schema for WADL files, schema documentation, and some tools which generate documentation and client-side Java stubs from an input WADL file. The specification is an advanced draft, but it is not clear where further standardisation will take place, nor when. As with WSDL, the goal with WADL is to document an interface in a machine-readable form. For example, the following WADL file describes a simple interface which allows clients to GET HTML representations of resources:
<application xmlns="http://research.sun.com/wadl/2006/10"> <resources base='http://example.org/resource'> <resource path='{resourceName}'> <doc>This resource is one of a set of resources</doc> <param name='resourceName' style='template'> <doc>The name of the resource being described</doc> </param> <method name='GET'> <response> <representation status='200' mediaType='text/html'> <doc>Returns a description of the resource</doc> </representation> <fault status='404' mediaType='text/html'> <doc>If the document is not found, return an explanation</doc> </fault> </response> </method> </resource> </resources> </application>
This describes a set of resources http://example.org/resource/{resourceName} for different values of the 'variable' {resourceName}. A GET request may produce one of two responses, namely a text/html response with a 200 status, or another text/html response, describing an error, with a 404 status.
In the case of WS-* services, a WSDL description is almost essential;there are so many technicalities involved in making a WSDL call, that a client application author is almost certain to make mistakes if they attempt to implement the client interface by hand. Also, the expectation of WS-* services is that the contents of the request and response are representations of program objects, which must be serialised into a request, and deserialised from a response, again introducing many opportunities for error.
The REST paradigm, however, avoids the fragility of WS-* services, by insisting that the contents of HTTP responses (and HTTP requests where appropriate) be _representations_ of the corresponding resources, encoded in one or other MIME type included in the HTTP request or response. This implies that the problems of serialisation and deserialisation are external to the protocol; this makes the interface easier to describe, with the strong advantage that the separation between the interface and the representations it carries is more clearly distinct.
Although this appears to place more of a burden on the client application, this is not the case in practice: since an application generally has to ingest representations of resources anyway, from files or other URLs, it is usually capable of ingesting representations from a RESTful interface without difficulty. What this means in turn is that a RESTful interface is generally rather straightforward to implement on the client side, with a lot less 'glue' which is specific to the interface.
In consequence, there is a much lesser need for the sort of generated code stubs which are a crucial output of WSDL tools. This is fortunate, since the code-generation tools distributed with the WADL standard seem immature, sometimes failing on valid input, and appearing to work naturally only for that subset of services which have a predominantly keyword-value GET interface.
In the experience of one of the present authors (skua, NG), a WADL file is a useful component of a RESTful service, even without any generated client code. The WADL file provides a usefully explicit specification of the service's interface, which was used to generate human-readable documentation and, using another custom XSL transformation, to generate code which verified that the service's test cases exercised all of the interface, and did not violate it at any point. A variant of this checking code could have been (but was not in fact) included within the server to guarantee that the service's responses matched its interface promises.
Thus on this and similar cases, the WADL file was useful enough, internal to code-base, to justify its use, and offering the WADL file to users of the service was an added bonus.
REST oriented frameworks and tools (not exhaustive)
Ruby on Rails ruby
Rails is a framework written in Ruby and dedicated to Web developments. See ruby for more details.
Restlet restlet
Restlet is a framework for the Java platform providing native REST fielding00 support. See restlet for more details.
Django django
Django is an open source framework for the Python expected to provide a native REST fielding00 support in the coming months. See django for more details.
NetKernel netkernel
NetKernel is an implementation of a resource-oriented computing abstraction. It can be thought of as an internet-like operating system running on a microkernel within a single computer. It is available with 2 kinds of license: open source and commercial. See netkernel for more details.
Apache CXF cxf
Apache CXF is an open source services framework designed to build and develop services using front-end programming APIs. Protocols such as SOAP, XML/HTTP, RESTful HTTP, or CORBA and of transports such as HTTP, JMS or JBI are possible. See cxf for more details.
Comments
REST development or compliant frameworks are evolving quickly so we think that we have not to recommend one or two of them.
Restfulness in the VO
Interoperability problems
As said in a previous part of this document, REST fielding00 is not a standard. The SOAP approach which was a key element in the IVOA architecture is a standard but is also crushed under a huge stack of related standards (WS-*). As a minimum it would be very efficient to have a “standardized” description of the REST fielding00 services provided in the frame of the IVOA. It could also be useful to have a tool to check if the service is really RESTful.
Use of a non-standard way (WADL for example)? Definitions of our own standard? Interaction with other WG (Registry…)?
Recommendations
Since REST is not a formal standard, but instead a set of good practices, services cannot be required to 'conform' to REST in any meaningful way. We RECOMMEND, however, that future services should conform to these good practices wherever possible, and that service authors should seek feedback on their interface design from the GWS WG, with a view to ensuring that the service conforms to the spirit of these practices as much as possible.
Although WADL is not, or not yet, a standard, we cannot require conformance to that, either. However the practical advantages to a service implementation of having a machine-readable interface specification (as described in section 3.4 above), and the interoperability advantages of having a public commitment to an interface, are substantial enough that we RECOMMEND that services publish a WADL file.
Work to done
The WADL spec (section 5) suggests that WADL documents should be
served using the application/vnd.sun.wadl+xml
MIME type,
and there are suggestions elsewhere that they should be available at a
http://example.org/service?wadl URL (though
this is not mentioned in the WADL spec). Should we echo this, and
generally be more prescriptive here?
Conclusion
Compared to SOAP Web Services REST fielding00 is a lite way to provide a Web service following just a reduced set of rules. But it is perhaps necessary to define clearly the basis of what an interoperable RESTful VO service must be. REST fielding00 is more human oriented than SOAP but it defines no standard concerning the description of the service which is important in the case of a dynamic use by other services. At least we recommend to provide the description of a REST service through a formalism like WADL.
References
$Revision$ $Date$