Table of Contents
The main features of REST are:
These features are part of the HTTP design, thus HTTP can be considered a REST protocol and REST services are based on HTTP. Using URLs to identify resources, MIME types to identify types of data representation and using requests that contain all the state required to process the request.
Currently REST services are typically implemented using HTTP, so it helps to know a little about the protocol and how it works.
HTTP defines four request methods which interact with URL:
REST Web Services currently tend to only use the
In addition to the request method and URL optional header values can be included with the request. These are implemented as key/value pairs and can appear on both the request and the response. Headers which can be important in REST requests are:
A list of commonly used headers is available in Wikipedia.
The response from a HTTP server includes a status code, this indicates if the request was handled successfully, the service has moved or if an error occurred. The status code is also accompanied by a brief description for presentation to the user. Common examples include:
A complete list of the standard status codes can be found in Wikipedia. In a few cases the complete protocol is implemented by the Web Services server (e.g. DAS), which can mean the standard codes have a slightly different meaning. Check the documentation of the Web Service for details of status codes which are used by the service.
The data returned by the service can be in a variety of formats. Hints on how to handle the data returned can be found in the Content-Type header. If defined the Content-Type header contains the MIME type 4) (Wikipedia) of the body content, which can be used to pass the data on to an appropriate viewer application or software module.
Some commonly used MIME types:
A complete list of official MIME types is available from IANA. Some applications may use unofficial MIME types to allow data to be directed to external applications.
How errors are communicated to the client is one area where REST services are very diverse:
The exact mechanism used should be described in the documentation accompanying the service.
Due to the flexibility offered by REST individual services have their own behaviours and resource nomenclature. However there are some types of service that have well defined specifications which are widely implemented:
These standards provide mechanisms to discover the capabilities of a service and how to invoke it at run time. This is useful when building clients since much of the work involved in interacting with a service can be handled by code generation, dynamic classes or client libraries. However it is necessary to know which type of service being accessed for the mechanisms provided to help.
A range of generic mechanisms exist for describing REST Web Service APIs:
Currently WADL is seeing some adoption with the development of tools such as RESTDescribe/RESTCompile, the use of WADL in Jersy the reference implementation for JAX-RS 21) and the appearance of some services providing WADL descriptions, for example:
WSDL 2.0 is also seeing use, for example: the SPARQL Protocol for RDF 22) specification uses WSDL 2.0 to define the interface. Tools to manipulate WSDL 2.0 are appearing and Web Services tool-kits (e.g. Apache Axis2 23)) are starting to support WSDL 2.0.
4) RFC2046 - Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types - http://www.faqs.org/rfcs/rfc2046.html
13) Dowell R.D., Jokerst R.M., Day A., Eddy S.R. and Stein L. (2001)
The distributed annotation system.
BMC Bioinformatics 2:7; DOI: 10.1186/1471-2105-2-7; PubMed: 11667947
15) RESTful Services Description Language (Resedel) - http://recycledknowledge.blogspot.com/2005/05/resedel.html
16) Simple Message Exchange Descriptor (SMEX-D) - http://www.tbray.org/ongoing/When/200x/2005/05/03/SMEX-D