What is REST?

I read a few articles about this but I still don't understand the
significance of it. Could someone please describe (in layman's terms)
what REST is and how it relates to Rails?

Thanks,
David

Sorry for the short answer but after just re-reading a part of it again last night I’d really recommend ‘RESTful Web Services’ (http://www.oreilly.com/catalog/9780596529260/
). I think it does a really good job of describing the concept but more importantly it provides some good examples for more abstract concepts, for example; it demonstrates a financial transaction done restfully.

You may want to read and join the two ongoing discussions on that very
topic.

Michael

Actually, I think the Wikipedia page does a good job of explaining
what REST is.

Here's an excerpt from the page that I found to be especially useful
in understanding REST in Rails:

REST's central principle: resources

An important concept in REST is the existence of resources (sources of
specific information), each of which can be referred to using a global ... etc

...

I have already added a response to one of the earlier threads in this
digest on REST - and have just come across and read these additional
threads. Reading the above extract from Wikipedia, I would ask what
has that definition got to do with the REST/CRUD/... concepts being
developed in the Rails world. Reading the other posts there really
does seem to be a growing need for definition. Not necessarily what
is REST itself, but more to be clear what is being spoken about by the
Rails stuff, ie. some new clearer terminology and definitions so that
we all know what we is being discussed. REST just seems to be a
fluffy term that doesnt really say very much at all - in a practical
sense.

tonypm

tonypm said the following on 07/01/08 07:49 AM:

Reading the other posts there really
does seem to be a growing need for definition. Not necessarily what
is REST itself, but more to be clear what is being spoken about by the
Rails stuff, ie. some new clearer terminology and definitions so that
we all know what we is being discussed. REST just seems to be a
fluffy term that doesnt really say very much at all - in a practical
sense.

Which is why I got frustrated when people here just reapted what is
available in Wikipedia and in many other blogs and 'casts on the 'Net.

Like you, I'm after some practical stuff.

At last, it seems to be coming through from people like Michael Ivey and
Michael Schuerig.

Thaks guys.

You're performing CRUD operations on Resources.

And a lot of times, that's all it is. For instance, adding, deleting, modifying and displaying users via /users.

Sometimes it's not just CRUD. Here's an example that came up on #merb the other day.

Say you have a list of users at /users ... and that you're logged in as an admin, and want the ability to bulk-delete users. So you add checkboxes next to each name...but where do they go?

You could write some JS to send a series of DELETEs to each of those users, but that kind of sucks.

So make it go to create().

Now, that sounds crazy, I agree. It is, but here's why it makes perfect sense from a resource-oriented view.

When you create a user, you POST the data for the new user to /users which, in English, is "Hey /users, would you make me a user that looks like [this]?"

So, you could also POST a list of ids as part of a request to /users that would mean, in English, "Hey /users, delete these for me, OK?"

Because Rails maps a POST to the collection to create() you have to put it in create().

I need more coffee, so this rambles a little, but I hope you can see my point.

I think that some people are getting too hung up on DHHs analogy
between the PGPD of HTTP and the CRUD of database access.

I've come to think of REST as a paradigm shift in the design of
client-server interface design and implementation akin to the paradigm
shift of object-oriented programming. Much like Smalltalk defined a
computation model based on objects with encapsulated state
communicating solely by sending mesages. REST structures the
computation as resources which can be created (using the http post
operation), retrieved (using get), changed (using put), and deleted
(using delete). REST could be thought of as using HTTP as a
programming paradigm, not just as a 'transport layer.'

Now, in Rails many resources are naturally mapped to active record
concepts, with many resources being persistently held in the database.
But in general, resources are more general than that. For example,
look at how the restful_authentication plugin turned the design used
by the acts_as_authenticated plugin into a restful design. In
restful_authentication login is accomplished by creating a session
resource, and logging off by deleting that resource. The session
resource is not represented as an AR model, but instead, and bear with
me because the terminology gets a little twisted, as a current_user
attribute in the Rails session.

In rails, the natural translation of resources is to map resources to
controllers, where each controller acts somewhat as a resource 'class'
and can respond to requests:

    To LIST all current instances (i.e. GET the collection of all
current instances of that 'class'), via an HTTP get of a url naming a
resource
    representing that collection, mapped to the index action.

   To CREATE a new instance of the 'class', via an HTTP post(with
initialization values) to that same url mapped to the create action.
The
    controller's new action acts as a HTML-HTTP adapter which allows
browsers to generate such a request through a form submission.

   To GET an instance via an HTTP get of a url naming that instance,
mapped to the show action.

   To UPDATE that instance via an HTTP put (with attribute values) to
the same url, mapped to the update action, with the edit action
   having a similar relationship as that between create/new.

   To DELETE that instance via an HTTP delete to the same url, mapped
to the destroy action.

What happens in those actions often maps to ActiveRecord CRUD
operations, but doesn't have to be.

Designing a Rails app using this discipline takes a bit of
acclimatization to the new paradigm, but many find the result leads to
a cleaner design, with less arbitrary decisions on where to put
things.

I'm glad to see the latest two posts on this list. I really started to
feel that I had missed something important, but Michael's and Rick's
descriptions fall very much in line with my own thinking about REST in
Rails.

It seems very clear to me that the Rails implementation follows the
"textbook" definition of REST very nicely. Yes there are some
extension to the concepts laid out in REST. This is born from
necessity. For example REST defines four operations on a resource
(POST, GET, PUT, DELETE). But when working with a web browser we also
needed a way to GET the forms used to create and update a resource. So
in Rails implementation of REST they decided to extend REST into seven
actions (create, show, update, delete, new, edit, and index). A non-
browser consumer of the service provided really only needs to care
about five of these (create, show, update, delete and index). These
actions, according to convention, should be named exactly as shown.
That's not REST, that's the Rails convention.

Now that being said; it's also possible to introduce additional
extensions yourself. However, any time you do that you are now
required to define and expose those custom actions to the consumers of
your service. From the service provider's perspective this is simply
adding a new method to the controller of the resource, but there is no
longer a way for the consumer to infer the API. The API must be
provided.

So sometimes adding a new resource to perform that custom behavior
actually simplifies the design to consumers, where from the inside may
seem to make it more complex. If the custom operation is exposed as
just another resource to be manipulated then the consumer can infer
the API. As a custom action of an existing resource the consumer
cannot make that inference which then forces the consumer to add
complexity to his application as well.

But still 4 verbs. GET /users/new is the resource for "New User Form" not a new verb on a user.

But still 4 verbs. GET /users/new is the resource for "New User
Form" not a new verb on a user.

Exactly, thanks for the clarification Michael. :slight_smile:

I hear this kind of "discoverability" touted, both with REST and with
WSDL. But my question is this: Has there ever been a real-world web
service that didn't have to document its API - REST or not?

The idea of someone accessing resources simply by knowing HTTP verbs
seems unlikely to me. In fact, the idea of "user-friendly URLs"
doesn't resonate, either. I don't access information on the Web by
typing URLs - I click links, and I couldn't care less what the href
is.

(This isn't an argument about REST in general, and doesn't apply to
web services.)

///ark

Rick DeNatale said the following on 07/01/08 12:56 PM:

I think that some people are getting too hung up on DHHs analogy
between the PGPD of HTTP and the CRUD of database access.

I've come to think of REST as a paradigm shift in the design of
client-server interface design and implementation akin to the paradigm
shift of object-oriented programming. Much like Smalltalk defined a
computation model based on objects with encapsulated state
communicating solely by sending mesages. REST structures the
computation as resources which can be created (using the http post
operation), retrieved (using get), changed (using put), and deleted
(using delete). REST could be thought of as using HTTP as a
programming paradigm, not just as a 'transport layer.'

Now **THAT** is a useful analogy.
(Especially to old ST hackers and people who used AppleTalk!)

Now, in Rails many resources are naturally mapped to active record
concepts, with many resources being persistently held in the database.

Step 1: Resource === controller of a single model

But in general, resources are more general than that. For example,
look at how the restful_authentication plugin turned the design used
by the acts_as_authenticated plugin into a restful design. In
restful_authentication login is accomplished by creating a session
resource, and logging off by deleting that resource. The session
resource is not represented as an AR model, but instead, and bear with
me because the terminology gets a little twisted, as a current_user
attribute in the Rails session.
[...]

What happens in those actions often maps to ActiveRecord CRUD
operations, but doesn't have to be.

The restful_authentication example is good here, once you add 'forgot
password, 'change password', 'reset password', 'process activation key'
for the e-mail confirmation, and the 'acts as stateful' transitions,
suspect, active, unsupend, purge ... things become interesting. Those
have to be mapped.

seven actions (create, show, update, delete, new, edit, and index).

But still 4 verbs. GET /users/new is the resource for "New User
Form" not a new verb on a user.

and terms like API, infer, standard

These are tangible things that I can relate to

Thank you
Tonypm