REST (Representational State Transfer) and RESTful web services: Methods, Concepts and Examples

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. As such, it is not strictly only a method of building what are sometimes called “web services.” The terms “representational state transfer” and “REST” were introduced in 2000 in the doctoral dissertation of Roy Fielding, one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification. The terms have since come into widespread use in the networking community.

REST strictly refers to a collection of network architecture principles which outline how resources are defined and addressed. The term is often used in a looser sense to describe any simple interface which transmits domain-specific data over HTTP without an additional messaging layer such as SOAP or session tracking via HTTP cookies. These two meanings can conflict as well as overlap. It is possible to design any large software system in accordance with Fielding’s REST architectural style without using HTTP and without interacting with the World Wide Web. It is also possible to design simple XML+HTTP interfaces which do not conform to REST principles, and instead follow a model of remote procedure call. The difference between the uses of the term “REST” therefore causes some confusion in technical discussions.

Systems which follow Fielding’s REST principles are often referred to as “RESTful”.

Most introductions to REST start with the formal definition and background. I’ll defer this for a while and provide a simplified, pragmatic definition: REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used (which often differs quite a bit from what many people actually do). The promise is that if you adhere to REST principles while designing your application, you will end up with a system that exploits the Web’s architecture to your benefit. In summary, the five key principles are:

• Give every “thing” an ID
• Link things together
• Use standard methods
• Resources with multiple representations
• Communicate statelessly

Let’s take a closer look at each of these principles.

The term REST was defined by Roy T. Fielding in his PhD thesis (you might actually want to follow that link — it’s quite readable, for a dissertation at least). Roy had been one of the primary designer of many essential Web protocols, including HTTP and URIs, and he formalized a lot of the ideas behind them in the document. (The dissertation is considered “the REST bible”, and rightfully so — after all, the author invented the term, so by definition, anything he wrote about it must be considered authorative.) In the dissertation, Roy first defines a methodology to talk about architectural styles — high-level, abstract patterns that express the core ideas behind an architectural approach. Each architectural style comes with a set of constraints that define it. Examples of architectural styles include the “null style” (which has no constrains at all), pipe and filter, client/server, distributed objects and — you guessed it — REST.

If all of this sounds quite abstract to you, you are right — REST in itself is a high-level style that could be implemented using many different technologies, and instantiated using different values for its abstract properties. For example, REST includes the concepts of resources and a uniform interface — i.e. the idea that every resource should respond to the same methods. But REST doesn’t say which methods these should be, or how many of them there should be.

One “incarnation” of the REST style is HTTP (and a set of related set of standards, such as URIs), or slightly more abstractly: the Web’s architecture itself. To continue the example from above, HTTP “instantiates” the REST uniform interface with a particular one, consisting of the HTTP verbs. As Fielding defined the REST style after the Web — or at least, most of it — was already “done”, one might argue whether it’s a 100% match. But in any case, the Web, HTTP and URIs are the only major, certainly the only relevant instance of the REST style as a whole. And as Roy Fielding is both the author of the REST dissertation and has been a strong influence on the Web architecture’s design, this should not come as a surprise.

Finally, I’ve used the term “RESTful HTTP” from time to time, for a simple reason: Many applications that use HTTP don’t follow the principles of REST — and with some justification, one can say that using HTTP without following the REST principles is equal to abusing HTTP. Of course this sounds a little zealous — and in fact there are often reasons why one would violate a REST constraint, simply because every constraint induces some trade-off that might not be acceptable in a particular situation. But often, REST constraints are violated due to a simple lack of understanding of their benefits. To provide one particularly nasty example: the use of HTTP GET to invoke operations such as deleting an object violates REST’s safety constraint and plain common sense (the client cannot be held accountable, which is probably not what the server developer intended). But more on this, and other notable abuses, in a follow-up article. (more)

Why REST?

REST-style services (i.e., RESTful services) adhere to a set of constraints and architectural principles that include the following:

RESTful services are stateless. As Fielding writes in Section 5.1.3 of his thesis, “each request from client to server must contain all the information necessary to understand the request, and cannot take advantage of any stored context on the server.” RESTful services have a uniform interface. This constraint is usually taken to mean that the only allowed operations are the HTTP operations: GET, POST, PUT, and DELETE. REST-based architectures are built from resources (pieces of information) that are uniquely identified by URIs. For example, in a RESTful purchasing system, each purchase order has a unique URI. REST components manipulate resources by exchanging representations of the resources. For example, a purchase order resource can be represented by an XML document. Within a RESTful purchasing system, a purchase order might be updated by posting an XML document containing the changed purchase order to its URI.

Fielding writes that “REST-based architectures communicate primarily through the transfer of representations of resources” (Section 5.3.3). This is fundamentally different from the Remote Procedure Call (RPC) approach that encapsulates the notion of invoking a procedure on the remote server. Hence, RPC messages typically contain information about the procedure to be invoked or action to be taken. This information is referred to as a verb in a Web service request. In the REST model, the only verbs allowed are GET, POST, PUT, and DELETE. In the RPC approach, typically many operations are invoked at the same URI. This is to be contrasted with the REST approach of having a unique URI for each resource.

These are the basic principles behind REST. However, when people talk about the benefits of RESTful systems today, they usually are not strictly applying these principles. For example, among REST advocates, keeping shopping cart data on the server and maintaining a session related to the shopping process that is using the cart is acceptable. (Storing session information or shopping cart data on the server is a clear violation of Fielding’s original REST concept since it violates the requirement that a service be stateless.) In fact, the XML/HTTP Binding provided by JAX-WS for implementing RESTful services provides for session management capabilities using cookies, URL rewriting, and SSL session IDs.

More significant deviations from Fielding’s definition of REST involve getting around the “uniform interface” constraint by embedding verbs and parameters inside URLs. The Amazom.com REST interface, for example, includes verbs in query strings and doesn’t have unique URIs for each resource. Systems like this, although labeled as RESTful, are really starting to look very much like RPC using XML over HTTP without SOAP.

For the purposes of this book, I am not going to wade into a debate on what is or isn’t RESTful. I simply define RESTful Web Services in contrast to SOAP Web Services. Table 3–1 illustrates the principal differences. (more)

What are the differences among SOAP, XML-RPC, and REST?

EXPERT RESPONSE FROM: David Linthicum

SOAP, or Simple Object Access Protocol is an XML-based object invocation protocol, and was originally developed for distributed applications to communicate over HTTP. SOAP defines the use of XML and HTTP to access platform independent services.

In contrast, XML-RPC is a Remote Procedure Calling protocol that works over the Internet, and is really an XML-RPC message that is an HTTP-POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML.

* REST is a bit different. REST (REpresentative State Transfer) is a technique for implementing Web services using XML documents plus standard HTTP, using its well-known operations (PUT, GET, POST, DELETE). The service-specific API is created by defining URIs (typically URLs) and XML documents that model the data structures and requests/responses required. REST has some very useful properties, e.g. you can use standard firewalls for security, standard caching for performance, while still letting you do everything that SOAP and XML-RPC can do.

ReST Vs SOA(P)

REST Applied to URI

Uniform Resource Identifiers (URI) are both the simplest element of the Web architecture and the most important. URI have been known by many names: WWW addresses, Universal Document Identifiers, Universal Resource Identifiers, and finally the combination of Uniform Resource Locators (URL) and Names (URN). Aside from its name, the URI syntax has remained relatively unchanged since 1992. However, the specification of Web addresses also defines the scope and semantics of what we mean by resource, which has changed since the early Web architecture. REST was used to define the term resource for the URI standard, as well as the overall semantics of the generic interface for manipulating resources via their representations.

• Redefinition of Resource
• Manipulating Shadows
• Remote Authoring
• Binding Semantics to URI
• REST Mismatches in URI

REST Applied to HTTP

The Hypertext Transfer Protocol (HTTP) has a special role in the Web architecture as both the primary application-level protocol for communication between Web components and the only protocol designed specifically for the transfer of resource representations. Unlike URI, there were a large number of changes needed in order for HTTP to support the modern Web architecture. The developers of HTTP implementations have been conservative in their adoption of proposed enhancements, and thus extensions needed to be proven and subjected to standards review before they could be deployed. REST was used to identify problems with the existing HTTP implementations, specify an interoperable subset of that protocol as HTTP/1.0, analyze proposed extensions for HTTP/1.1, and provide motivating rationale for deploying HTTP/1.1.

The key problem areas in HTTP that were identified by REST included planning for the deployment of new protocol versions, separating message parsing from HTTP semantics and the underlying transport layer (TCP), distinguishing between authoritative and non-authoritative responses, fine-grained control of caching, and various aspects of the protocol that failed to be self-descriptive. REST has also been used to model the performance of Web applications based on HTTP and anticipate the impact of such extensions as persistent connections and content negotiation. Finally, REST has been used to limit the scope of standardized HTTP extensions to those that fit within the architectural model, rather than allowing the applications that misuse HTTP to equally influence the standard.

• Extensibility
• Self-descriptive Messages
• Performance
• REST Mismatches in HTTP
• Matching Responses to Requests

RESTful Web Services

This chapter describes the REST architecture and RESTful web services, and explains how to use the REST API to create RESTful web services.

What Are RESTful Web Services?

Representational State Transfer (REST) is a software application architecture modeled after the way data is represented, accessed, and modified on the web. In the REST architecture, data and functionality are considered resources, and these resources are accessed using Uniform Resource Identifiers (URIs), typically links on the web. The resources are acted upon by using a set of simple, well-defined operations. The REST architecture is fundamentally a client-server architecture, and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture, clients and servers exchange representations of resources using a standardized interface and protocol. These principles encourages REST applications to be simple, lightweight, and have high performance.

RESTful web services are web applications built upon the REST architecture. They:

• expose resources (data and functionality) through web URIs
• use the four main HTTP methods to create, retrieve, update, and delete resources

RESTful web services typically map the four main HTTP methods to the so-called CRUD actions: create, retrieve, update, and delete. The following table shows a mapping of HTTP methods to these CRUD actions.

Table 6-1 HTTP Methods and their Corresponding CRUD Action

HTTP Method	CRUD Action
GET	Retrieve a resource.
POST	Create a resource.
PUT	Update a resource.
DELETE	Delete a resource.

(more)

Putting REST on Rails

“Convention over configuration” is one of the key principles behind the design of Ruby on Rails. It was built with a specific way of doing things and as long as you follow the “Rails way” everything will just work with little or no configuration. That’s part of the reason Rails is so successful–as long as you follow its conventions you get many benefits with less work than other frameworks that require you to be more explicit.

The HTTP protocol is very similar in this respect. Stray from the path and you’ll find yourself hacking together replacements for basic things HTTP gives you for free. Stay on the path and you gain benefits like caching and better scalability of your applications with less effort. A well-designed–which typically means a RESTful–web application makes good use of available HTTP methods, rather than relying on GET requests to trigger server state changes.

The ideal is to dispatch to a different handler based on the HTTP method, actually running different code depending on the method, and making it impossible to unintentionally change state with a GET request.

(more)

Getting Started with RESTful Rails

Since DHH’s keynote at RailsConf there has been a lot of talk about RESTful rails. I finally decided to get up to speed and start exploring. This is a look at the new scaffold_resource and routing that will be in Rails 1.2.

The Rails application is a sort of “jukebox” or more accurately a list of artists and their albums. But enough about the name, let’s get started. (more)

Online REST Web Service Demo

This online demo is an example of a RESTful Web Service. The service was implemented using the principles of the REpresentational State Transfer architectural style. It exposes the Hypersonic sample database as Web Service.
Using HTTP and XML, resources can be queried, removed and altered. A Web browser like Firefox or MS Internet Explorer can be used for queries. (more)

NetBeans REST Web Services, Building and Deploying

[wikipedia.org]
[http://www.webreference.com]
[http://www.infoq.com/]
[http://tssblog.techtarget.com/]
[http://developers.sun.com]
[http://www.slideshare.net/]
[http://railsforum.com/]
[http://searchsoa.techtarget.com/]
[http://www.thomas-bayer.com/]