What exactly is RESTful programming?

Question

What exactly is RESTful programming?

Don't give me links to wikipedia please, I'm hoping for a straight-forward answer, not some BUZZ-word-ful answer.

Bonus question: Should I feel stupid because I never heard about it outside SO?

Answer 1

Really, what it's about is using the true potential of HTTP. The protocol is oriented around verbs and resources. The two verbs in mainstream usage is GET and POST, which I think everyone will recognize. However, the HTTP standard defines several other such as PUT and DELETE. These verbs are then applied to resources.

For example. Let's imagine that we have a user database that is managed by an web service. Using the non-restful approach it would probably look something like this:

/user_create
/user?id=xxx
/user_edit?id=xxx
/user_delete?id=xxx

A restful application would probably expose an API with a single base resource.

/user
/user/xxx

If you want to create a new user you simply send a POST request to that URL with the data you want to create. If you want to retrieve a user you send a GET request to /user/xxx. If you want to update a user you simply send the fields you want to update using a POST request to /user/xxx. If you want to delete it, you send a DELETE request instead.

An even more concrete example. In a RESTful application you'll never modify data using a GET request. This is what POST and DELETE is for. Most web applications do this all the time, though, and are therefore not RESTful.

There's an article called How I explained REST to my wife. As I recall, that's the first time I really got it. :)

You might also want to take a look at WebDAV which extends HTTP and adds even more verbs. Subversion uses this, for example.

Answer 2

It's programming where the architecture of your system fits the REST style laid out by Roy Fielding in his thesis. Since this is the architectural style that describes the web (more or less), lots of people are interested in it.

Bonus answer: No. Unless you're studying software architecture as an academic or designing web services, there's really no reason to have heard the term.

Answer 3

REST is using the various HTTP methods (mainly GET/PUT/DELETE) to manipulate data.

Rather than using a specific URL to delete a method (say, /user/123/delete), you would send a DELETE request to the /user/[id] URL, to edit a user, to retrieve info on a user you send a GET request to /user/[id]

For example, instead a set of URLs which might look like some of the following..

GET /delete_user.x?id=123
GET /user/delete
GET /new_user.x
GET /user/new
GET /user?id=1
GET /user/id/1

You use the HTTP "verbs" and have..

GET /user/2
DELETE /user/2
PUT /user

Answer 4

I see a bunch of answers that say putting everything about user 123 at resource "/user/123" is RESTful.

Roy Fielding, who coined the term, says REST APIs must be hypertext-driven. In particular, "A REST API must not define fixed resource names or hierarchies".

So if your "/user/123" path is hardcoded on the client, it's not really RESTful. A good use of HTTP, maybe, maybe not. But not RESTful. It has to come from hypertext.

Answer 5

IMHO (and I tend to be in the minority), RESTful programming is about:

• resources being identified by a persistent identifier: URIs are the ubiquitous choice of identifier these days
• resources being manipulated using a common set of verbs: HTTP methods are the commonly seen case - the venerable Create, Retrieve, Update, Delete becomes PUT, GET, POST, and DELETE
• the actual representation retrieved for a resource is dependent on the request and not the identifier: use HTTP Accept headers to control whether you want XML, HTTP, or even a Java Object representing the resource
• maintaining the state in the object and representing the state in the representation
• representing the relationships between resources in the representation of the resource: the links between objects are embedded directly in the representation
• resource representations describe how the representation can be used and under what circumstances it should be discarded/refetched in a consistent manner: usage of HTTP Cache-Control headers

The last one is probably the most important in terms of consequences and overall effectiveness of REST. Overall, most of the RESTful discussions seem to center on HTTP and its usage from a browser and what not. I understand that R. Fielding coined the term when he described the architecture and decisions that lead to HTTP. His thesis is more about the architecture and cache-ability of resources than it is about HTTP.

If you are really interested in what a RESTful architecture is and why it works, read his thesis a few times and read the whole thing not just Chapter 5! Next look into why DNS works. Read about the hierarchical organization of DNS and how referrals work. Then read and consider how DNS caching works. Finally, read the HTTP specifications (RFC2616 and RFC3040 in particular) and consider how and why the caching works the way that it does. Eventually, it will just click. The final revelation for me was when I saw the similarity between DNS and HTTP. After this, understanding why SOA and Message Passing Interfaces are scalable starts to click.

I think that the most important trick to understanding the architectural importance and performance implications of a RESTful and Shared Nothing architectures is to avoid getting hung up on the technology and implementation details. Concentrate on who owns resources, who is responsible for creating/maintaining them, etc. Then think about the representations, protocols, and technologies.

Answer 6

I apologize if I'm not answering the question directly (I'm new to SO and don't have pts to comment), but it's easier to understand all this with more detailed examples. Fielding is not easy to understand due to all the abstraction and terminology.

There's a fairly good example here:

Explaining REST and Hypertext: Spam-E the Spam Cleaning Robot

And even better, there's a clean explanation with simple examples here (the powerpoint is more comprehensive, but you can get most of it in the html version):

http://www.xfront.com/REST.ppt or http://www.xfront.com/REST.html

After reading the examples, I could see why Ken is saying that REST is hypertext-driven. I'm not actually sure that he's right though, because that /user/123 is a URI that points to a resource, and it's not clear to me that it's unRESTful just because the client knows about it "out-of-band."

That xfront document explains the difference between REST and SOAP, and this is really helpful too. When Fielding says, "That is RPC. It screams RPC.", it's clear that RPC is not RESTful, so it's useful to see the exact reasons for this. (SOAP is a type of RPC.)

Answer 7

This is what it might look like:

POST /user
fname=John&lname=Doe&age=25

The server responds:

200 OK
Location: /user/123

In the future, you can then retrieve the user information:

GET /user/123

The server responds:

200 OK
<fname>John</fname><lname>Doe</lname><age>25</age>

To update:

PUT /user/123
fname=Johnny

Answer 8

A great book on REST is REST in Practice. Slides for their jaoo tutorial pdf.

Must reads are Representational State Transfer (REST) and REST APIs must be hypertext-driven

See Martin Fowlers article the Richardson Maturity Model (RMM) for an explanation on what an RESTful service is.

To be RESTful a Service needs to fulfill the Hypermedia as the Engine of Application State. (HATEOAS), that is, it needs to reach level 3 in the RMM, read the article for details or the slides from the qcon talk.

The HATEOAS constraint is an acronym for Hypermedia as the Engine of Application State. This principle is the key differentiator between a REST and most other forms of client server system.

...

A client of a RESTful application need only know a single fixed URL to access it. All future actions should be discoverable dynamically from hypermedia links included in the representations of the resources that are returned from that URL. Standardized media types are also expected to be understood by any client that might use a RESTful API.client that might use a RESTful API. (From Wikipedia, the free encyclopedia)

REST Litmus Test for Web Frameworks is a similar maturity test for web frameworks.

Approaching pure REST: Learning to love HATEOAS is a good collection of links.