What is REST?

The Representational State Transfer (REST) architectural style for services, first described by Ron Fielding ¹⁾, was inspired by the development of Hypertext Transfer Protocol (HTTP) ^{2) 3)}.

The main features of REST are:

• Client-Server: clients act as interfaces to server based services
• Stateless: each request must contain all the information required to interpret the request
• Cache: response data can be marked as cacheable or non-cacheable allowing use of caching at server, client or intermediate proxies.
• Uniform Interface
  • Identification of resources: unique identifiers (e.g. URLs or URIs) for specific resources
  • Manipulation of resources through representations: requests and responses are representations of objects (e.g. HTML or XML documents)
  • Self-descriptive messages: provision of meta-data describing the type of representation (e.g. MIME type)

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:

• GET: retrieve the resource addressed by the URL
• PUT: send a resource to be placed at the address specified by the URL
• POST: send data to the URL and optionally receive a response
• DELETE: remove the resource addressed by the URL

REST Web Services currently tend to only use the GET and POST methods since these are well supported by proxies and firewalls, unlike the PUT and DELETE methods. Services which support PUT and DELETE usually provide alternative resources to support these methods via a GET or POST for compatibility.

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 ⁴⁾ (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:

1. Web Services servers which directly implement the HTTP protocol (e.g. DAS) often use the HTTP status code mechanism to communicate error conditions.
2. Some services use additional HTTP headers to indicate error conditions
3. Others use error documents as part of the body content (e.g. dbfetch)

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:

• AtomPub (http://www.atomenabled.org/): an API for performing queries on categorized data and publishing data. Commonly used in blogging software, AtomPub is also used as a basis for APIs such as the Google Data API.
• Distributed Annotation System (DAS) ¹³⁾ (http://www.biodas.org/): used to get sequence data and associated feature annotation.
• OpenSearch (http://www.opensearch.org/): an API for performing searches and getting search results. Commonly used for web browser search plug-ins, OpenSearch can also be used as an API if RSS or Atom feeds are used to describe the results.
• Search/Retrieval via URL (SRU) (http://www.loc.gov/standards/sru/): an API for performing searches and getting search results.

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:

• Norm's Service Description Language (NSDL) ¹⁴⁾
• RESTful Services Description Language (Resedel) ¹⁵⁾
• Simple Message Exchange Descriptor (SMEX-D) ¹⁶⁾
• Web Application Description Language (WADL) ¹⁷⁾
• Web Description Language (WDL) ¹⁸⁾
• Web Resource Description Language (WRDL) ¹⁹⁾
• Web Services Description Language Version 2.0 (WSDL 2.0) ²⁰⁾

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 ²¹⁾ and the appearance of some services providing WADL descriptions, for example:

• WSDbfetch (REST)
• QuickGO

WSDL 2.0 is also seeing use, for example: the SPARQL Protocol for RDF ²²⁾ 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 ²³⁾) are starting to support WSDL 2.0.