Translated by Stefan Maibcher (December 2008).

From
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. TheREpresentational 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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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>
Listing 1: Representation of a Shopping Cart
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.

Figure 1: 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.
1
2
3
4
5
6
7
8
9
10
PUT /article

<articles>
<name>Tea</name>
<description>
Herbal Tea from South Africa
</description>
<price>2.80</price>
<unit>100 grams</unit>
</article>
Listing 2: PUT Request
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.

Figure 2: 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.
Table 1: HTTP Methods
Method Description
GET GET queries the representation of a resource. The execution of requests should be free from side
effects. GET requests can be sent arbitrarily often. You cannot blame the client for effects caused by
GET requests. That means a GET can be sent heedlessly.
POST With POST you can change the state of a resource. For example you can add a good to a shopping
cart. POST isn't free from side effects. For example you can change fields in a data base or start a new
process on the server with a POST request.
PUT New resources can be produced with PUT or you can replace the content of existing resources.
DELETE Resources can be deleted using DELETE.
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.

Figure 3: 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 Maibcher (December 2008).