First, exactly what is REST?

REST is a new and improved form of web services. REST is a software architecture approach to connecting different software systems together that emphasizes interface simplicity and uniformity. REST was invented primarily because “traditional” web service calls - calls that use SOAP and WSDL - are not simple and they are not uniform. Everyone seems to implement traditional web services differently, so using someone else’s web service is often confusing and difficult. REST web services don’t typically use SOAP or WSDL at all (but if they do they use them in very simplified forms). The idea is that by making it far easier to understand and use remote “resources” (especially web services), web services might become as widely used as web pages are on the Internet. This is the goal of REST.

What does REST stand for and why?

REST stands for “representational state transfer” and was first presented by Roy Fielding Footnote 1: I guess I should say “Doctor Roy Fielding” since I assumed he passed. Seems like it would be pretty hard to fail that guy. in his Ph.D. dissertation back in June of 2000 (accurately re-enacted in the cartoon here). Why the term “representational state transfer”? I was afraid you might want to know. The term is reeeaaalllly academic. It’s not a bad idea to skip the remainder of this paragraph since the explanation is confusing as hell. Not going to take my advice, eh? Turn back now! This is your final warning. The idea is that all URLs (like ) return the representation of some web resource (like a web service call, a file, a database, an image, etc.) When you get that resource it puts you in a different state. Because everything looks like a simple URL in REST, you can easily request another resource (or “transfer” to another “representational state”) from wherever you are currently at. You don’t need to process a WSDL file – you just call the next URL directly. The basic idea is that RESTful Footnote 2: A term used in RESTful Web Services, by Leonard Richardson and Sam Ruby. See the “Where Can I Learn More?” section. architectures try to make it just as easy for software programs to chain through web services as it is for humans to follow hyperlinks across a set of web pages. Resources in REST architectures are fast to implement, easy to understand and use, and quick to link together. OK – perhaps that paragraph wasn’t that bad, but the next one is really horrible.

What is a resource oriented architecture (ROA)?

A Resource Oriented Architecture (or ROA) has come to mean a specific type of a REST architecture that focuses its technology set on HTTP, XML, and URLs Footnote 3: The book RESTful Web Services distinguishes between Resource Oriented Architectures and RESTful architectures in this manner. . So REST is the more general term and ROA is more specific, but since most REST systems use HTTP, XML, and URLs, the distinction is pretty trivial (I told you this paragraph would be horrible). But the term REST is widely used as a synonym for resource-oriented architectures and it takes discipline, determination, and willpower to correctly use the right term in the right place. We don't have any of these qualities, so we’ll join the REST of the world and use the terms loosely as synonyms.

Why was REST and ROA created?

The ROA style was created because SOA architectures that use traditional web services have unnecessary complexity (take two aspirin and see the chapter on WSDL). ROAs make it much easier to expose and to consume web services, not by adding another layer of software, but by making some basic simplifying assumptions, getting rid of WSDL and SOAP, and encouraging a set of best practices especially about how to properly use HTTP.

So where is the REST standard? I can't find it.

There isn’t a standard for REST architectures or for ROA any more than there is a standard for the “object-oriented” or “client-server” architectural styles. But even without standards, you can usually tell a RESTful architecture when you see one if you know the four things to look for, which we’re about to cover in a moment. But first – another warning. It’s hard to talk about REST without talking about HTTP, SOAP, WSDL, and web services, which makes for some very dry reading – especially this sentence here. So you might want to read the chapters on those other technologies first before enduring this chapter and also to get a good warm-up before trying to tackle the level of dryness in this section. Seriously though, REST is beginning to catch on even though there are very few tools that support the style, and it’s a very clever idea and worth understanding, so let’s jump into it.


Quickly - what are the REST basics?

Roy Fielding recognized four key properties that made internet web pages so successful and also that traditional web services lack. Those properties are:

  • uniformity
  • addressability
  • connectedness
  • statelessness

To understand each of these properties in the context of web services or of REST, it’s helpful to first consider each of them in the context of everyday ordinary internet web pages. For example, all web pages that you surf across are accessed uniformly, in the same way, with simple URLs. They pretty much all look like And all web pages are individually addressable. That is, you don’t have to go to a company’s home page every time you want something off one of their web pages. You can just hop directly to the information you’re looking for by making the URL a little more specific (like Web pages are also very connected since you can simply embed hyperlinks from one page to another. Following a chain of hyperlinks is trivial – you just click on the next hyperlink. And web pages are stateless on the server side. Once a web server gives you a copy of a web page, it forgets about you. Resource oriented architectures attempt to give web services these same properties since they are the properties that make web pages work so well for humans. Now that you understand what these properties mean, let’s go into a little more detail on these four properties and compare RESTful services to traditional SOAP/WSDL services.

Quick - give me the first of the two key differences between traditional web service calls and REST service calls.

REST web service calls are uniformly accessed. There are two key differences between REST web service calls and traditional SOAP/WSDL-based web service calls that make the REST calls more uniform. First, in a REST web service call, the action to be performed by the service is specified in the “METHOD” portion of the HTTP header. So REST web service calls look like this “http://database/table/record” and not like this “http://database?method=searchTable”. This may not seem like a big deal, but imagine if you had to stop and think for a while about exactly what to type in to the browser every time you went from web site to web site. You might still visit plenty of web sites, but you probably wouldn’t hop across web sites so quickly. This is essentially what programs that call traditional web services have to do because of the inconsistent placement of the method information. And chaining across web services is complicated too. If a web service returns some information that then points to another web service, the client program has to go get the WSDL file for that remote service, parse it, figure out how to assemble the URL string, and then call that next web service. Its “state transfer” is very difficult.

Sidebar - REST and traditional SOA applications both must specify if they are trying to create, update, retrieve, or delete something during a method call. How do they differ?

(Managers may want to skip this part. Errrrrr... I mean just this box - not the whole book.)


Since REST URLs look like http://database/table/record, then how does the service know if you’re retrieving the record or deleting it? In REST, if you’re, say, trying to delete something, you use the HTTP DELETE method, which is buried in the HTTP header and not visible in the URL itself. If you’re trying to retrieve something, you use the HTTP GET method. This is different than how traditional SOAP web services do it. With SOAP-based web services, the HTTP method is always set to “POST” regardless if you’re trying to create, retrieve, update, or delete (“CRUD”). But if SOAP calls don’t use the HTTP method, then how is the action specified? The answer is that traditional web service calls use one or both of the following techniques to specify what action the server should perform:

  1. The name of the method (“delete”, “get”, “update”, etc.) is specified in the URL itself. Traditional web service calls are invoked by passing the web server something that looks like this: ?method=doGoogleSearch. The verb “doGoogleSearch” is embedded directly in that URL.
  2. The name of the method to call is embedded in the SOAP message body. If you look closely at the SOAP XML message in the Google example above, you’ll find the string “doGoogleSearch” somewhere inside.

Most traditional web service calls use both of these approaches. Note that the verb that defines the action is inconsistent. That is, the verb might be “doGoogleSearch”, “doSearch”, “ImBeggingYouPleaseSearch” or just “search”. You don’t know what word to use unless you look at the service vendor’s WSDL file. With REST web services, the verb is always “GET”, across all companies and all services and it’s always in the same place.

OK what's the second?

Second, with a “RESTful” web service, qualifying information is specified in the message body. In other words, somewhere you need to specify exactly what order you are trying to delete, what customer should be updated, or which account should be debited. With REST, the information that narrows the scope of the action that is taking place always resides in the XML message body. Where do traditional web services place this information? Traditional web services frequently put this information directly in the URL (as in They also might put the information in the message body, but they might not. REST web service calls always place qualifying information in the same place – in the message body. Again, this consistency facilitates hoping from one service to another since all RESTful web services look the same.

So what does "uniformity" really mean?

So in ROAs, web services are accessed through calls to URLs in a very uniform fashion. They identify the method they want to call in the same way, and they qualify the request in the same way. That covers the first of the four properties. Let’s now revisit the “addressable” property in a little more detail (only much more quickly than the first one).

So what does "addressability" really mean?

Resource oriented architectures are also said to be “addressable”. This means that even the smallest object in the system has its own URL. So, for example, a record in a database might be accessed like this: http://department/motorvehicles/trucks/myRedTruck. A traditional web service typically does not provide a separate URL for each miniscule data element. Rather, they provide specific methods to access that data, as in:“myRedTruck”Footnote 4: My two year old son Spencer is pretty into red trucks right now. He seems to feel this is an important topic to cover when conversing about Resource Oriented Architectures. . In this example, a special web service was created to find trucks. With REST, a more generalized interface is constructed so that the database (or whatever the resource is) can be accessed through a URL to its finest level of granularity. In REST architectures, there’s usually an almost limitless set of valid URLs. Traditional web service environments usually provide under 100 web services so they have under 100 valid URLs.

So what does it really mean to be "connected"?

RESTful services are highly “connected” (the third property). This ultimately means you can easily nest web service calls within the output of other web service calls. Or, perhaps a more proper way of looking at this is that you can easily nest resources inside of other resources. A data structure that has embedded somewhere inside of it the URL of a remote web service (like /department/motorvehicles/trucks/myRedTruck) automatically has embedded within it a pointer to another web service call. Following the chain is trivial – you just hit another URL (just like a hyperlink). Unlike in traditional web service environments, you don’t have to parse another WSDL file to follow the link.

So what does it really mean to be "stateless"?

Finally, REST services are “stateless”. No client-specific information is ever stored on the server. This makes it much easier to horizontally scale applications. If a REST system is running slowly, just add more servers. If a machine in that system fails, another server can easily take over for the first since session state does not have to be transferred from one machine to the other. If a client application doesn’t receive a response from a service (or “resource”), it can just ask for it again.

Sidebar - If REST is stateless, how are database commits handled?

You may be wondering how, if REST is stateless, does it handle something like a pending database commit? One technique is for the server to create a temporary resource that then has shared ownership by the server and the client. The REST folks have thought of techniques to handle all kinds of tricky situations, including two-phase commits.

Sidebar - What’s WADL?

WADL is like WSDL for REST Footnote 10: If Roy Fielding is reading this, he just had a coronary. If you’re standing next to his body right now, please dial 911. . WADL files provide a list of all the services (or resources) that are valid to call, just like WSDL does. Sometimes it’s obvious what the resource URLs should look like and you don’t need WADL, but sometimes you need a little guidance on what the available resources are. Moreover, some services still need clarifying information about what operations are valid to perform on it (for example, you may not be able to delete all resources), what parameters the service expects, and what XML schemas should be applied. But unlike WSDL, WADL provides a very simple file format to spell out this kind of information. REST interfaces are so uniform and simple, you can usually figure out and write your own WADL file if you need to or just forgo creating a WADL file at all. Imagine trying to write a WSDL file for someone else’s SOAP-based web service.

Wrap up this excerpt - I'm out of time.

Note that the underlying technologies that support ROAs are HTTP, URLs, XML, and WADL. So REST (or more precisely ROA) really does rid us of SOAP and WSDL. Imagine how great it would have been if you never had to suffer through those WSDL and SOAP chapters! What a relief that would have been – especially to have be spared that horrible joke on the bottom of page 103. ROAs use a simpler and more proven set of technologies. ROAs replace SOAP with plain old XML and HTTP, so method calls still pass through firewalls just fine. ROAs replace WSDL with careful HTTP method placement and sometimes with a little WADL too (see sidebar - "What's WADL?").


So how well does REST really work and will it ultimately thrive?

Of course, the really big question is whether REST will catch on.  Is this a technology that seems like a good idea but came too late, or is it going to become a commonly used approach?  How well does it work in practice?  Where is a REST approach best applied and where is it a mistake?  Your software guys may be touting REST as the way your organization should go, but aren’t those the same guys who promised you a lot of code reuse a few years back when C++ and Java was the rage?  It's worth it to find out the answers to these questions (especially when it's a easy read and you can write off the purchase as a business expense!)  Leverage off our years of painful experiences in the trenches dealing in cold, hard, gritty reality (rather than in theory or proof-of-concept projects). Click the “Buy Now” button below and act to keep your career firm, erect, and moving upward. Don't just settle for the book excerpt on this web page - get the whole picture.