
Learn REST: A Tutorial - parenthesis
http://rest.elkstein.org/
======
stiff
If people would simply advocate building applications which follow the
semantics of HTTP instead of advocating "REST", many more people would
understand the benefits and conform; there would be no need to write a
thousand and one posts explaining what is REST. Unfortunately the original
exposition of this way of building web applications was done in a
dissertation, in a "scientific" style that I think Orwell captured so well
(<http://www.mtholyoke.edu/acad/intrel/orwell46.htm>, worth a subscription of
its own). Another problem is that unfortunately most web developers (not to
mention "SEO experts") don't have any real understanding of HTTP or the
principles behind the WWW, which makes them also unaware of the very practical
problems certain design decisions can cause.

------
glenjamin
One thing I've always struggled with with REST, is how you should handle
additional verbs.

As a contrived example, say we have a booking

    
    
        GET /booking/:id
    

And we then want to cancel this booking, more specifically we want to trigger
the "cancel" action (transition), which would change the state of the booking
from "active" to "cancelled". There are a few possible ways to do this, and
I'm not really sure which is "correct" for REST, or whether it actually
matters:

    
    
        POST /cancel (booking = /booking/:id)
        PUT /booking/:id (state = cancelled, note this is dictating the resulting state, not the transition)
        POST /booking/:id/cancel
        CANCEL /booking/:id (custom verb, good/bad ?)

~~~
hammerdr
POST /cancellation { :booking_id => 123 }

In general, it is not wrong to noun-ify domain concepts such as a
cancellation.

~~~
glenjamin
I can see why this would be the case given the constrains imposed by the the
REST architecture, but I don't really see what benefits this has over having
some sort of "cancel" action to be performed on the booking resource.

Sidenote: Is it "better" to pass booking_id = number, or booking = booking
resource URL. Why?

~~~
icebraining
_> I can see why this would be the case given the constrains imposed by the
the REST architecture, but I don't really see what benefits this has over
having some sort of "cancel" action to be performed on the booking resource._

The problem isn't so much REST, but HTTP: using a custom method could have the
potential of creating havoc with proxies and such.

 _> Sidenote: Is it "better" to pass booking_id = number, or booking = booking
resource URL. Why?_

I think the ID should be the URL. It decouples the client from the internal
IDs, which is not only DRYer (since otherwise you'd effectively have two IDs)
as it can help if you need to change the internal ID format.

------
gte910h
>Rather than letting clients construct URLs for additional actions, include
the actual URLs with REST responses. For example, a "product list" request
could return an ID per product, and the specification says that you should use
<http://www.acme.com/product/PRODUCT_ID> to get additional details. That's bad
design. Rather, the response should include the actual URL with each item:
<http://www.acme.com/product/001263>, etc. Yes, this means that the output is
larger. But it also means that you can easily direct clients to new URLs as
needed, without requiring a change in client code.

This a thousand times yes.

~~~
jwingy
If you have your routes designated in a central area , this shouldn't be a
problem anyways right? In fact, you need to designate this someplace anyways,
whether it's on your server (in the database or in some code), or on the
client-side code.

I might be missing something here though or just not quite understanding the
problem.....

~~~
masklinn
> If you have your routes designated in a central area , this shouldn't be a
> problem anyways right?

It's not a problem for the server (and even then, it might be: what if the
root handler simply sends to further sub-handlers after just chopping off part
of the URL or query arguments? There isn't necessarily a central URL authority
on the servier either), but generally is one for the client: in a truly
RESTful system, the client _knows_ one URL and one only (the service's root).

It also _knows_ all the media types the service can return (which is why
meaningful content-types, as those returned by Github, are great).

From this, it can traverse the service to the place it needs, and it _may_
cache URLs along the way (for more efficient traversals later on) but those
URLs may die altogether and require a re-traversal.

This scenario is _built into_ the architectural style.

> In fact, you need to designate this someplace anyways, whether it's on your
> server (in the database or in some code), or on the client-side code.

If URLs are designated anywhere in the client-side code (outside of the root
service URL and a URL cache, which is accumulated knowledge rather than built-
in), it's not a RESTful service, it's RPC-over-HTTP.

~~~
jwingy
>If URLs are designated anywhere in the client-side code (outside of the root
service URL and a URL cache, which is accumulated knowledge rather than built-
in), it's not a RESTful service, it's RPC-over-HTTP.

But certainly the client needs to know something about the base resources such
as product or user? How else will the client know where it can fetch the
appropriate resource?

~~~
pornel
It will know by discovering URLs on each step — the same way you browse a
website without knowing all of its URL structure in advance. Each HTML
response has links and forms that show how to get the next thing.

~~~
jwingy
Ahh, I think I understand where I'm misinterpreting things. I've been building
a purely javascript based website so I've been thinking from that perspective
instead of the more traditional page by page approach where this makes more
sense when described in these terms.

It's definitely still possible to build a RESTful service, but I think if
you're primarily building in js, you tend to have more routes that return
resources without URLs to other resources than ones that do, especially when
you're just starting out and don't have a comprehensive list of resources you
want to represent and the accepted mime-types you'd like to be able to return.

------
sambeau
This is missing a few salient points:

1) REST is not suited to complex multi-variable queries or transactions

2) REST should be a stateless transaction

3) REST read results should be cacheable

4) REST can use headers to specify content-type/mime-type

REST is not a suitable replacement for all client-server interactions e.g.
complex, sql-like queries over many variables. It is best suited to URL-like
queries that produce singleton docs or lists of doc IDs.

REST in its most common form is a protocol over HTTP and thus can (and should)
take advantage of HTTP's methods to provide CRUD:

    
    
      Create  = POST
      Read    = GET
      Update  = PUT (although POST is fine)
      Delete  = DELETE
    

This negates the need for:

    
    
      /story/395/delete
    

or

    
    
      /delete/story/395
    

instead use

    
    
      /story/395
    

and send it a DELETE method.

~~~
bodhi
For the sake of debate:

> REST is not suited to complex multi-variable queries or transactions

Would it not be possible to represent a query or transaction as a resource,
that you could GET/PUT like any other?

> REST should be a stateless transaction

I think there's a small grey area here around "stateless transaction". The
HTTP request/response itself should be atomic (to be a bit loose with
terminology), but the result can change the state of the system.

So the _communication_ between client and server is the part of the system
that is stateless. (Apologies if this was your intended meaning.)

~~~
sambeau
_The HTTP request/response itself should be atomic_

One of the great advantages of REST is that makes data caching easy.
Statelessness is a requirement for caching.

 _"Would it not be possible to represent a query or transaction as a
resource"_

Anything's possible just about but the whole point of REST is to create
uniform resource locators for data. The problem with creating rather forced
complicated URIs is that you quickly lose uniqueness: the same data will start
being represented by more than one URI and therefore will start to be cached a
multiple of times leading to conflicts.

------
kragen
It seems to me that if you want to learn REST, you'd be better off reading
Roy's dissertation, which is pretty short and doesn't contain bullshit like,
"Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete)
operations."

~~~
masklinn
I'd recommend reading his blog instead, especially his analysis of services
claiming RESTfullness. The thesis is not exactly clear, and I did not grasp
the significance of what's now called "HATEOAS", the importance of media types
and the lack of importance of URLs (as well as the complete irrelevance of
"pretty" URLs to the restfullness of a service) until I read his blog posts on
the subject.

------
arturnt
REST != HTTP. HTTP, which is the language of the web is just an example of a
REST implementation. A lot of people get this wrong. This should say _Restful_
for everything, not REST.

Also to be REST compliant you have to employ discoverability and hypermedia.

Read: [http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven) <http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>

------
schiptsov
There are two big ideas in REST. First one is in realm of system engineering,
and second one in the realm of programming paradigms.

Using HTTP[S] protocol allows you to pass through almost every heterogeneous
network. That means any highly restricted and protected (I prefer the term
'misconfigured') network of a cell phone provider, who blocks everything else,
but http.

You can survive in that crazy hotel's or airport's wi-fi network, especially
located in developing countries, which is a mess of cheap Chinese ADSL-modems
and no-name Wi-Fi access-points with settings no one cares about.

It also means that you can pass through all these almost useless corporate
firewalls made by idiots (why firewall if you have all those windows with IE6
boxes running by users with admin rights?).

The second big thing is about statelessness and using URI as a namespace -
representing data as a file-system hierarchy and using one standard protocol
everywhere - it is almost the same ideas which lays on the foundation of this
enlightening Plan9 system. No xml, no BS, just names and simple standard
protocol - 9P.

Together, those two ideas are enough to forget about all that proprietary
crap, not because it is proprietary, but because REST is more general,
flexible and easy to implement concept.

------
emperorpenguin
Can somebody explain in one sentence why is REST a good thing? What does it
bring to the party? Why is forcing every RPC call that my application makes
into CRUDdable objects necessarily a good thing?

Frankly, I can't believe the amount of near-religious attention it's being
given. You're taking an obscure aspect of HTTP (already a mind-bendingly
terrible protocol in its own right) - verbs - and making it the cornerstone of
your application framework.

~~~
artsrc
REST facilitates loose coupling between clients and servers, scalability,
caching, retrys etc. REST is a good thing because it provides the right
abstractions for some applications.

A slow, unreliable interaction with a remote server is different than an
interaction with an in process function call.

If ignoring this complexity is causing no problems then concentrate on what
does cause you problems, then just learn enough about REST to recognize a
problem in the future.

~~~
emperorpenguin
But how does REST improve scalability, caching, retrys, etc... over _ANY_
other HTTP-request based scheme?

~~~
artsrc
Exactly which other HTTP based scheme?

SOAP v1.0 tunneled everything over POST so you could not cache responses.

A frequent non-restful solution is to return a domain specific id to a client
and have the client 'know' that the correct URL is say
<http://{base}/product/{id}>.

The restful solution is to return the URL to the client have them use it what
is given rather than construct it. The restful solution allows for many
product servers which are independent from the original server. This makes for
looser coupling and improved scaling.

REST is essentially what they were thinking, or now think they should have
been thinking, when they designed HTTP. So truly honoring the spirit of HTTP
gets you close to REST.

~~~
emperorpenguin
Ok - fair enough. SOAP sucks.

But we've known to use GET for operations with no side-effects, and POST for
operations that change stuff for many years now, without needing to attach a
name to it, throw PUT/DELETE into the mix, or CRUDdifying _every_ operation.

It's the verb part that I really don't get. That, and the general level of
excitement surrounding REST. Why are there so damn many articles like this
one?

~~~
artsrc
The advantage of the PUT/DELETE verbs is that they are idempotent. If they
fail an intermediary or you can safely just apply them again on the same or a
different server.

The author of this article has a different understanding of REST than I do.
For instance I strongly disagree with this: "One option is not acceptable as a
REST response format, except in very specific cases: HTML, or any other format
which is meant for human consumption and is not easily processed by clients."
I think well marked up HTML is potentially the best response format as long as
it is easily understood by clients. And I think this has nothing much to do
with REST. Naturally I become motivated to write my own article about REST
spelling out how my understanding is is different. Thus the number of articles
on REST multiples as a chain reaction until 99.99% of the articles on the
internet are about REST. But my 1 year gave me a bad sleep last night
dampening the my motivation and saving the world.

------
extension
_In many ways, the World Wide Web itself, based on HTTP, can be viewed as a
REST-based architecture._

In _every_ way, the WWW is a REST-based architecture. REST is an analysis of
the web, as it existed at the time. There is no more perfect exemplar of REST.

This is a crucial point. Fielding's paper is about how and why the web works.
It's not, per se, about how the web should be used to make network services,
though many have tried to derive that from it.

------
jebblue
The real focus for web services needs to return to SOAP. SOAP is a truly
contractual design that solvs many of the problems that have to be solved by
hand in REST, do we use JSON or what to transfer the data? How about argument
types? REST is like a nice way to express HTTP other than that SOAP was
designed to and solves web service problems very well.

~~~
icebraining
(I find it very distasteful to downvote parent's comment without replying.
It's a valid opinion, not a troll)

You're right that REST doesn't provide everything SOAP does, because SOAP is a
specific protocol and REST is just an architectural style. On the other hand,
there are already specific protocols to achieve that in a REST style (and
reusing HTTP), like WADL.

Furthermore, it's not clear that a one-size-fits-all approach like SOAP takes
is the right way. XML is great for some use cases but not others; by
pigeonholing everything to it you create inefficient systems filled with hacks
to avoid its shortcomings in certain domains.

SOAP in particular seems very strict, while REST based systems - particularly
the Web - are designed to make an heterogeneous mix of decoupled services and
clients work well together. The idea that a client should break if the schema
changes, for example, leads to very brittle systems.

~~~
jebblue
>> The idea that a client should break if the schema changes, for example,
leads to very brittle systems.

Thanks for that, much appreciated.

>> The idea that a client should break if the schema changes, for example,
leads to very brittle systems.

That's the point, imagine building the web using string values instead of
constants. With constants, if it changes, you immediately get notification
from the IDE via the compiler and can fix it straight away. If it's a string,
then it's up to the poor testers to find it and good luck, it has to be in a
known use case.

I think for general communications REST is better than not following any
standard by far. For web services though, my money is still on SOAP and I'm a
Java/Linux lover not .NET these days, SOAP is still best for Web Services in
my view.

------
clark-kent
This seems like REST tutorial for SOAP users. I would have liked it if they
just described REST. Not always comparing it to SOAP.

------
postfuturist
An article describing rest should link to rfc2616 which actually has quite a
bit to say about using HTTP and REST (without ever using that term).
<http://tools.ietf.org/html/rfc2616>

------
lhnz
What happens when you need to request some data and therefore use the GET
method, but also are passing sensitive data in the query? Should you use POST
in this case in order that the sensitive request is not logged?

