What is a concise way of understanding RESTful and its implications?

Question

*update: horray! so it is a journey of practice and understanding. ;) now i no longer feel so dumb.

I have read up many articles on REST, and coded up several rails apps that makes use of RESTful resources. However, I never really felt like I fully understood what it is, and what is the difference between RESTful and not-restful. I also have a hard time explaining to people why/when they should use it.

If there is someone who have found a very clear explanation for REST and circumstances on when/why/where to use it, (and when not to) it would benefit the world if you could put it up, thanks! =)

Answer 1

This article does a good job classifying the differences in several http application styles from WS-* to RESTian purity. What I like about this post is it reminds you that most of what we call REST really is something only partly in line with Roy Fielding's original definition.

InfoQ has a whole section addressing more of the "what is REST" angle as well.

In terms of REST vs. SOAP, this question seems to have a number of good responses, particularly the selected answer.

Answer 2

REST is usually learned like this:

1. You hear about REST being using HTTP the way it was meant to be used, and from that you shun SOAP Web Services' envelopes, since most of what's needed by many SOAP standards are handled by HTTP in a simple, no-nonsense way. You also quickly learn that you need to use the right method for the right operation.
2. Later, perhaps years later, you hear that REST is more than that. REST is in fact also the concept of linking between resources. This often takes a while to grasp the full meaning of, but when you learn this, you start introducing hyperlinks into your responses so that clients can navigate your system without being coupled to how the server wants to name its resources (i.e. the URIs).
3. Even later, you learn that you still haven't understood REST! And this is because you find out that media types are important. You start making media types called application/vnd.example.foo+json and put hyperlinks in them, since that's already your understanding of REST.
4. Years pass, and you re-read Fielding's thesis for the umpteenth time, to see if there's anything you missed, and it suddenly dawns upon you what really the HATEOAS constraint is: It's about the client not having any notion of how the server's resources are structured, but that it discoveres these relationships at runtime. It also means that the screen in front of the user is driven completely by what is passed over the wire, so in fact, if a server passes an image/jpeg then that's what you're supposed to show to the user, not an error message saying "AtomProcessor can't handle image/jpeg".

I'm just coming to terms with #4 and I'm hoping the ladder isn't much longer! It's taken me seven years.

Answer 3

I would imagine YMMV, but I found it very easy to start understanding the details of REST after I realised how REST essentially was a continuation of the static WWW concepts into the web application design space. I had written (a rather longish) post on the same : Why REST?

Answer 4

Scalability is an obvious benefit of REST (stateless, caching).

But also - and this is probably the main benefit of hypertext - REST is ideal for when you have lots of clients to your service. Following REST and the hypertext constraint drastically reduces the coupling between all those clients and your server, which means you have more freedom when evolving/developing your service over time - you are not tied down by the risk of breaking would-be-coupled clients.

On a practical note, if you're working with rails - then restfulie is a great little framework for tackling hypertext on the client and server. Server side is a rails extension, and client is a DSL for handling state changes. Interesting stuff, check it out here: http://restfulie.caelum.com.br/ - I highly recommend the tutorial/demo vids they have up on vimeo :)

Answer 5

Content-Type: text/x-flamebait

I've been asking the same question lately, and my supposition is that half the problem with explaining why full-on REST is a good thing when defining an interface for machine-consumed data is that much of the time it isn't. OK, you'd need a really good reason to ignore the commonsense bits (URLs define resources, HTTP verbs define actions, etc etc) - I'm in no way suggesting we go back to the abomination that was SOAP. But doing HATEOAS in a way that is both Fielding-approved (no non-standard media types) and machine-friendly seems to offer diminishing returns: it's all very well using a standard media type to describe the valid transitions (if such a media type exists) but where the application is at all complicated your consumer's agent still needs to know which are the right transitions to make to achieve the desired goal (a ticket purchase, or whatever), and it can't do that unless your consumer (a human) tells it. And if he's required to build into his program the out-of-band knowledge that the path with linkrels create_order => add_line => add_payment_info => confirm is the correct one, and reset_order is not the right path, then I don't see that it's so much more grievous a sin to make him teach his XML parser what to do with application/x-vnd.yourname.order.

I mean, obviously yes it's less work all round if there's a suitable standard format with libraries and whatnot that can be reused, but in the (probably more common) case that there isn't, your options according to Fielding-REST are (a) create a standard, or (b) to augment the client by downloading code to it. If you're merely looking to get the job done and not to change the world, option (c) "just make something up" probably looks quite tempting and I for one wouldn't blame you for taking it.