Home Notes Web development My explanation of REST (Representational State Transfer)

My explanation of REST (Representational State Transfer) E-mail
Sunday, 17 April 2011 12:01

There is a lot of information on the web about REST.  But I find much of it unclear, especially for someone without a background in how HTTP works and web application development.  I would like to provide my own (slightly verbose) definition of REST and also link to a handful of useful resources around the web on the subject.


My explanation

Background (source)

  1. First of all, REST is not a standard or any kind, it is a style of architecting web applications that aims to benefit from pre-existing features of the HTTP protocol, the protocol that essentially powers the Web.
  2. Under REST, "things" on the web that users are interested in and interact with are resources.  So on a blog site a particular blog post is a resource; a listing of all blog posts is also a resource.  On a shopping site any particular item is a resource, a listing by category is a resource, and so on.
  3. Users interact with resources in representations.  Again, for a blog site, viewing a blog post in a web browser is an HTML representation of that resource; viewing the blog post in an RSS reader is an XML representation of the same resource.
  4. Each interaction places the requesting client in a state, and each new interaction between the client (web browser, RSS reader, etc.) and server is a transfer that updates the state of the client.

What does it mean in practice?

An important thing to know:

  • Resources are represented by nouns.  That is, under a REST-ful application design, your URLs contain the identifier (ID, name, etc.) of the resource you are interacting with, and not some verb describing how you are interacting with that resource.

Let's say a resource is requested at a URL: http://www.somesite.com/blog/posts/a_blog_post

On its own the URL is ambiguous.  You may assume that a user is trying to view the blog post, but under REST, the same URL is used when you want to perform other operations on that resource, like edit or delete it.  So how does the application know what you are trying to do with the resource?  This is where HTTP comes in.

HTTP verbiage

HTTP has built into it four "verbs" that describe the type of interaction you are trying to perform.  If you're familiar with the common CRUD operations, this is how they map to those HTTP verbs:


CRUD Operation HTTP operation
Create POST
Read GET
Edit/Update PUT


So, here's the lesson: With every request sent to a server, two pieces of data are being transmitted:

  1. A noun - the identifier of the resource you are interested in
  2. A verb - an HTTP operation describing how you want to interact with that resource

The beauty of REST is that these descriptors being used are already present in the technologies that power the World Wide Web, so you're not inventing anything new, but simply taking advantage of something that's already there but for some reason has been overlooked.


  1. Instead of a URL like http://www.somesite.com/blog/posts/?id=1234&action=edit you can have something like http://www.somesite.com/blog/posts/1234, and the application knows you are trying to edit (instead of view or delete, for example) because the HTTP header that gets sent along with the request tells it so.
  2. Additionally, that same URL can grab an XML (or JSON, or some other) version of the same blog post.  What I didn't mention above is that a third piece of data is being transmitted with your request: the format you want the response in.


One clean and simple URL with many applications, thanks to protocols already built into the system.

The Art of Rails

One of the best explanations of REST is provided in Chapter 6 of the book The Art of Rails by Edward Benson.  Here are some worthy excerpts.

The Art of Rails

On representations

When I drive to work in the morning, I am using the physical representation of that resource. If I look at a photo of my car, I am looking at a graphical representation of that resource. When my transmission blew, the auto repair shop used their computers to pull up a repair-history representation of that resource. These are three different physical representations of the same conceptual entity, the resource.


Resource-oriented programming ... uses URLs to represent the resources contained within the system — the nouns — and makes the specification of actions to be performed on those resources secondary.

From the REST perspective, web applications are programs that observe and modify the states of those resources.

RESTful development suggests that developers return to using HTTP commands to specify the CRUD operation to be performed and to standardize on these commands as the common set of operations available for all resources contained within a web application.

The mandate that all RESTful resources be accessible by the same standard set of operations simplifies both API development and API use. Your web application API becomes the set of resource endpoints, and HTTP-based REST operations become the method calls into that API.

Other references