REST Web Services

Web services are usually associated with SOAP. Using the REpresentational State Transfer architecture, you can also realize Web services.This article describes REST on the basis of an example and describes the ideas and concepts of REST.

Introduction

Besides SOAP there is an alternative for the realization of Web services. In his dissertation Thomas Roy Fielding describes an architectural style he calles REpresentational State Transfer architecture , briefly REST. REST is based on principles, which are used in the largest distributed application - the World Wide Web. Without intention there are many search engines, shops or booking systems that are already available as REST based Web services. The REpresentational State Transfer architecture is an architecture that describes how the Web should work. REST is neither a product nor a standard.

1 Example of a REST Application

As an example for a RESTful application we use an online shop. In the shop customers can fill their shopping carts with goods. Each individual object of the application is reachable over an URL as a resource. For example you can reach the shopping cart no. 5873 by the following HTTP request:

GET /shoppingcart/5873

The structure of a response is not specified in REST. There must be a common understanding about the representation between client and server. The usage of XML makes a representation for computers as well as for humans comprehensible. For example, the representation of a shopping cart can look like the following listing:

HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0"?>
<shoppingcart xmlns:xlink="http://www.w3.org/1999/xlink">
  <customer xlink:href="http://shop.oio.de/customer/5873">
    5873
  </customer>
  <position nr="1" amount="5">
    <article xlink:href="http://shop.oio.de/article/4501" nr="4501">
      <description>Sugar</description>
    </article>
  </position>
  <position nr="2" amount="2">
    <article xlink:href="http://shop.oio.de/article/5860" nr="5860">
      <description>Earl Grey Tea</description>
    </article>
  </position>
</shoppingcart> 
        

As you can see in Listing 2, the server's response contains a XML document that the client can process. This document can be converted into HTML, SVG, PDF or something else by applying a XSL transformation. With XLink and XPointer the document can refer to further resources. Furthermore, you can formulate queries using XPath or XQuery.

The shopping cart contains two positions and the associated customer. Using XLink the positions refer to further resources, here the goods. The client can follow a link to query the representation of a good. In this way he changes his state.

GET /article/5860

With each document the client can enter more deeply into the web of application data. As point of entrance only one URL is sufficient. The idea of hypertext is applied to web services. In Figure 1 you can see a graph of resources connected by links. Thus, the client can follow the links to get from a resource to the next resource.

Figure1: HATEOAS (Hypermedia as the Engine of Application State)

1.1 Ordering or Triggering Operations on the Server

Candied sugar should not be missing in a good tea. So, the order must be extended by this important article. Suppose candied sugar has the article number 961. The following POST request adds candied sugar to the shopping cart.

POST /shoppingcart/articles&cart=5873&article=961
      

1.2 Creating New Resources

To create new resources you can use the HTTP method PUT.

PUT /article

<articles>
  <name>Tea</name>
  <description>
    Herbal Tea from South Africa
  </description>
  <price>2.80</price>
  <unit>100 grams</unit>
</article> 

Listing 6 shows the reply of the server. The HTTP status code 201 means "created" , i.e. a new resource was generated. To indicate the location of the newly created resource a HTTP location header field is used. The client can now follow the URL to a representation of the new article.

HTTP/1.1 201 OK
Content-Type: text/xml;
Content-Length: 30
Location: http://shop.oio.de/article/6005
      

1.3 Deleting Resources

To delete the newly created resource, you can use a HTTP DELETE request. The following DELETE request removes the article with the id 6005.

DELETE /articles/6005

This example has shown how to work with resources, HTTP methods and URLs. In the following sections we will go deeper into the details.

2 The World of REST

2.1 Resources

Web sides, pictures and CGI scripts are resources, that can be addressed using URLs. A web application is an accumulation of resources. With HTTP messages you can sent messages to the resources, for example by opening a website in the browser.

A direct manipulation of a resource is not intended. Each access is made indirectly using a URL that is assigned to the resource.

Figure2: Every Business Object gets its own URL

The semantics of the HTTP protocol is used by REST. In REST the HTTP methods GET, PUT, POST and DELETE play a central role. They are the "verbs" that are applied to the "nouns", respectively the resources. With this limited pool of four methods all use cases have to be covered.

2.2 Representations

The representation of a resource can refer to further resources. If a client follows a link in a representation, it makes a transition from a state into the next state.

Why the name REpresentational State transfer is used, becomes clear from the following scenario. A web browser requests a website, or more generally it requests a representation of a resource using an URL. A HTML document, which represents the resource is transferred from the server to the client. The HTML document can contain links, which refer to further resources in the web. If the client navigates to a new site he changes its state. Therefore, a transfer from a state to another has happened by following a link.

2.3 The Methods

The interface of REST is generic. There is no need for protocol conventions for the communication between client and server. The following list describes the meaning of the HTTP methods and how they are used by REST.

The HTTP methods GET, POST, PUT and DELETE are a generic interface for each REST resource. Database applications have shown that a limited set of commands controlling the lifecycle of data is sufficent. The database query language SQL covers the lifecycle by the SELECT, INSERT, UPDATE and DELETE instructions.

2.4 Messages

All types of documents can be used as representations for resources. For example HTML, GIF and PDF files are used in the Web. XML is suitable for the transmission of structured data. XML documents can use XLink for references. If you want to realize your application by using Rest, you don't have to learn a new format. You can use well-known formats.

REST messages are self explaining. In a message everything must be contained, in order to interpret the message. There is no knowledge about previous or later messages necessary for the interpretation of a message. The status of an application is represented by the contents of one or several hypertext documents.

2.5 State and Session

The server knows its state. He is not interested in the state of the client nor in sessions to its clients. The client has to manage its state itself. It decides the order in which it calls methods on the server, too.

Usually in REST applications no special functionality is needed for a login. All recources can be authenticated by available web technologies, e.g. HTTP and HTTPS.

3 Properties of a REST Application

The REST style is characterized by the following properties:

• Communication takes place on call. The Client is active and requests a representation from the passive server and/or modifies a resource.
• A resource can be addressed by an unique URI.
• The client can request the representation of a resource in form of a document.
• Representations can refer to further resources.
• The server does not monitor the status of its clients. Each query to the server must contain all informations that are necessary for interpreting itself.
• Caching is supported. The server can mark its answers as cacheable or not cacheable.

4 Advantages

4.1 Scalability

The enormous growth of the World Wide Web has shown in which extent web technologies scale. Millions of users use resources, which are offered by many thousand of servers. Proxys and caches increase the performance. Components such as servers, proxys and web applications can separately be installed and attended.

There are lots of formats like HTML, SVG, AVI,... Even new formats can be easily added with MIME types. The size of the transferred documents varies from few bytes to many megabytes.

In the web artificially sessions are generated with cookies and URL rewriting. These sessions are stateful. In this point REST deviates from the web. In REST all interactions are stateless - each operation stands for itself. The representations of the resources contain all necessary information. With HTTP there are no boundaries between the applications. By following a link you can arrive at a completely different application. Since all interactions are stateless, the servers have not to interact. This fact improves the applications' scalability.

4.2 Access to External Systems

There is no other application with so many legacy systems like the web. You can access an abundance of other systems via different gateways. The details of other external systems are hidden behind interfaces.

4.3 Independent Installable Components

In REST the deployment of the components can be accomplished indepentent by each other. The content of individual web sides can be exchanged without adapting further sides. Indepentent deployment is a prerequisite in very large systems like the World Wide Web or the email service of the internet.

4.4 Composition of services

It is easy to use individual REST services together. Strictly speaking, there are no REST services. There are only resources. URLs are offering a global address space so documents simply refer to a resource which is in another organization.

5 Comparison of REST and SOAP

The delivery of SOAP messages is comparable with a companies internal mail system. The letter baskets of the coworkers cannot be addressed directly. All letters are delivered at the house's post office. The house's post office must open the letters before and decides then, due to content, to whom the message is passed on. In a REST application the letter baskets are directly addressable. The SOAP specification version 1.2 approaches on REST in this point.

SOAP messages are always addressed to an endpoint, which is implemented by a SOAP router, also called dispatcher. SOAP router are realized through a Servlet or a CGI script. In illustration 3 you can see that the request is delivered to the dispatcher first. Each message is a HTTP POST to the same address.

SOAP is a protocol construction set used to write own apllication protocols. The protocol describes the structure of the request and the reply. The description of the request and the answer represents a rigid framework that cannot be easily changed. If the server would like to supply further information than so far, then it can not use the existing interface. A new web service is necessary so that already installed clients remain compatible. Using REST, the server can supply additional information and the interface of the web service can remain unchanged. In SOAP the possibility for the gradual evolution of existing Web services is limited.

The address space between REST and SOAP is a crucial difference. REST uses a global address space with URLs, over which each resource can be addressed. In REST the resource is the center of attention. There are no services in REST.

5.1 Generic Interfaces

REST offers with the GET, POST, PUT and DELETE methods a generic interface. In SOAP all methods for each application must be defined by yourself. Thereby, the development of generic tools and services in the web is obstructed.

5.2 Standards

REST recommends the use of established standards. For example, the following technologies are at the developers disposal:

• URLs for addressing
• HTTP methods for communication
• XML, XHTML, HTML, PNG, ... as data formats
• MIME types
• ...

The standards for HTTP and URIs are central. For the representation you can use arbitrary formats. Future technologies also can be used.

There are some standards like WSDL, UDDI, WS-Security designed exclusively for SOAP applications. REST standards are "real" web standards, used for many purposes, not only for REST.

6 How to build a REST application...

… or making an existing application RESTful? Distributed applications are based on functions or methods, that work on objects. The Client can access the objects of the server by using remote procedure calls. A REST application makes its objects visible with public URLs. Business objects have to be reachable over an URL and are represented by a document, preferably in XML.

Figure3: The SOAP Bottleneck

A REST servers core does not differ from a PRC application. The difference is in the interface layer that in REST fundamentally differs from a RPC application. REST uses HTTP methods, which work on URI addressable resources, while RPC makes available a component-based interface with specialized methods or functions.

7 Tool Support

There are already an immense number of tools for the introduced standards REST is based on. Apache or Microsoft IIS are REST compatible web servers, Tomcat is a REST compatible web container and Squid a REST compatible proxy server. There aren't any specialized REST tools necessary. But developers can benefit from special REST tools and APIs. By using JAX-RS for example, you can turn a simple Java POJO into a RESTful resource. Or relational databasea can be made accessable as REST resources using sqlrest .

8 Public REST Services

There is already a set of public Web services, which consciously use RESTful interfaces. For example Amazon, Google or O'Reillys Meerkat.

9 Conclusion

REST only uses ripe standards such as HTTP or URLs, which are available already for some years. It takes advantage of well-known ideas used in the web such as hypertext and a unbounded, global address space. Thus, REST based web services are real web services contrary to SOAP and the WS-* standard stack of protocols.

Translated from the German article REST Web Services . Thanks to OIO !

Translated by Stefan Maibücher (December 2008).

Resources

Architectural Styles and the Design of Network-based Software Architectures
(http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
,

Second Generation Web Services
(http://www.xml.com/pub/a/2002/02/06/rest.html)
,

Rest Wiki
(http://internet.conveyor.com/RESTwiki/moin.cgi)
,

Representational State Transfer
(http://www.xfront.com/REST.ppt)
Costello, Roger L.

REST and the Real World
(http://www.xml.com/lpt/a/2002/02/20/rest.html)
Prescod, Paul

The Emperor's New Tags - The SOAP/REST Controversy
(http://www.prescod.net/rest/soap_rest_short.ppt)
Prescod, Paul

A New Direction for Web Services
(http://www.sys-con.com/xml/article.cfm?id=454)
Prescod, Paul

Building Web Services the REST Way
(http://www.xfront.com/REST-Web-Services.html)
Costello, Roger L.

Hypertext Transfer Protocol -- HTTP/1.1
(http://www.ietf.org/rfc/rfc2616.txt)
,