
The one true REST explanation - jipumarino
http://martinfowler.com/articles/richardsonMaturityModel.html
======
joblessjunkie
I'm with him until he gets to "Hypermedia Controls", which strikes me as
needless bureaucracy.

The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element isn't really
helping anything. Before you can consume that service, you need to know what
"royalhope.nhs.uk/linkrels/slot/book" actually means, and if you already know
that, then having it listed here in the response justs wastes space.

He's disguising a custom verb under a cloak of some sort of 'standardization'
which isn't actually part of HTTP or any common web practice. The consumer of
this service will need to know what all the verb URIs mean and precisely how
to use them anyway, so listing them here doesn't provide any benefit and
significantly complicates the communication.

In this way, the "Hypermedia Protocol" doesn't demonstrate any edge over old-
school XML RPC.

Up until that point, I agreed with the article. Simple objects exposed using
standard HTTP verbs is the way to go -- but I stop short of supporting random
lists of verbs labeled with URIs as just more needless bureaucracy.

~~~
boucher
He states very explicitly that his examples weren't any kind of standard, as
one doesn't truly exist at that level.

I think the point he was trying to get across, and really what a lot of people
who are advocates for REST are trying to accomplish, is that in a fully
realized model computers would be able to understand how to talk to each other
to get information and update resource states without the need for human
intervention.

Clearly we are a long way from that goal, but I think it's still something
worth talking about.

~~~
DJN
Whilst the notion of "computers talking to each other without human
intervention" sounds like a utopian ideal, I think his method is a recipe for
disaster.

The domain of possible consequences of changing protocols and semantics on the
fly is hugely complex. What about testing? Are we advocating that we change
live systems without tests?

The author writes: "Level 3 introduces discoverability, providing a way of
making a protocol more self-documenting."

I reply: The same way good design separates presentation, logic and data, it
follows that good protocols separate data from documentation.

~~~
hammerdr
> possible consequences of changing protocols and semantics on the fly is
> hugely complex

Except when you assume that you're reading the semantics from each and every
response. It introduces some complexity to how clients need to accept
responses. However, once that part is done the changing protocol and semantics
should not disrupt the system.

And testing? That's not a very difficult component to test. Throw a few
different 'schemas' at the HTTP client response module and then feel safe to
drop that into your application. I believe you're imagining a system that is
more highly coupled to the response schema. This approach is meant to remove
that coupling entirely (well, except for a base uri :))

I agree that embedding <link />'s into the response is a violation of a
separation of concerns. They should probably be separated in some way (HTTP
headers?). However, there are precious few examples of this in the wild and we
may see some creative ways to separate these (I just hope we don't go the way
of XML to have a different resource to specify schema).

------
terra_t
I find it hard to believe that he's built real systems that work.

Yes, "decomposing services into multiple components" works well when
everything is living in the same address space, but if you want to build fast
and reliable systems, minimizing round trips is important.

If I didn't have anything better to do and if I liked dealing with idiots, I'd
hang my shingle as a high-priced consultant who helps "enterprises" dig their
way out of the REST morass. Just last year I managed to speed up an
application 100x by switching from REST to POX. In this case, the app was
doing thousands of round trips for no good reason other than architectural
purity.

In the real world, composite operations should be done, more or less, in
transactions. For instance, in one user authentication system I've worked on,
there are about ten database updates to create a new user. There really ought
to be one "createUser" call that creates the user. You could probably get away
with not having database transactions if you're talking to the database
locally, but in a distributed app on the wider internet, you just can't expect
to do ten communications in a row and have it work "reliably enough".

~~~
troygoode
You find it hard to believe that _Martin Fowler_ has built real systems that
work? He is a rather well known programmer, author, speaker, and Chief
Scientist at ThoughtWorks.

~~~
terra_t
I know who Martin Fowler is. I love his "Refactoring" book.

On the other hand, once you get famous, you can go around and get big $
telling people what they want to hear and you can lose your edge.

If this is representative of his work these days, he should preface it with
something like "I'm not a doctor but I play one on TV"

~~~
shadowfox
> If this is representative of his work these days, he should preface it with
> something like "I'm not a doctor but I play one on TV"

Really? That bad? Care to explain?

------
contextfree
It's always seemed to me that the difficulty with hypermedia controls is not
how to have your server expose them, which is straightforward enough, but how
to have your client do something useful with them.

It basically means writing your client as a state-graph navigating agent,
which makes it closer to AI-ish programming (not surprising, since the
argument for REST has been that web services should be structured more like
the human-browsable web) than the input -> output or interactive event-driven
paradigms that most programmers are more conversant with.

Yet the books and online evangelism etc. for REST that I've seen don't really
address this issue.

------
buro9
This stuff isn't new, it just isn't widely adopted yet.

OpenSearch does stuff like this:
[http://www.opensearch.org/Specifications/OpenSearch/1.1/Draf...](http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_4)

It describes an interface (Atom XML based) that further self-describes how it
was called and what you can do to it (how to search within results, for
example).

Simply applying that thinking to JSON based RESTful services gives you that
question "What can I do with this?", and that makes building the API easier...
for everything you serve describe what can be done with it and how you were
called.

This then totally de-couples the request from the client, the client can send
many queries and not care about them, and get back something that encapsulates
the state of the request (search terms), the state of the result (search
pagination) and the verbs for each entity (what you can do with it).

I never would've called this "Hypermedia Controls", I think that's confusing.

It's just having your interfaces describe themselves and be discoverable.
Coupled with a WADL-style thing (but probably not WADL itself... perhaps JSON
such as on the Freebase API: [http://code.google.com/p/google-
refine/wiki/ReconciliationSe...](http://code.google.com/p/google-
refine/wiki/ReconciliationServiceApi#Service_Metadata) ).

Perhaps we all just need a new catchphrase or buzzword though, just to get the
wider industry onboard? I'd rather just say that your services should be
discoverable, and that means within the results telling us what we can do, in
addition to a top level thing to describe which services exist.

------
IgorPartola
Are there any good examples out there of services that implement that last
level? I have seen and used the others but not discoverability.

~~~
smeatish
Check out twilio's documentation on their REST API:
[http://www.twilio.com/docs/api/2010-04-01/rest/response#hype...](http://www.twilio.com/docs/api/2010-04-01/rest/response#hypermedia)

Since their core product _is_ an API, they've done a really good job building
in all the levels of REST discussed in the article, including discoverability.

------
tszming
This is one of the best (but simple) explanation of REST.

~~~
boucher
Although intended for a different audience, I enjoyed this one when I read it:
<http://tomayko.com/writings/rest-to-my-wife>

------
numbakrrunch
nice writeup. caucho's "metaprotocol taxonomy" is great further reading,
contrasting REST with other common patterns/protocols:
<http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp>

------
wyuenho
I don't know if he had intended to put the REST zealotry to rest, but Martin
Fowler and Roy field seem to be on the same page when it comes to level 2
REST. I submitted this to HN a few weeks ago, I'm posting it here again:

<http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post>

I hope these 2 blog posts will just stop people from equating REST to full
HTTP.

------
mattberg
curious: why is the initial resource used to get the list of slots
/doctors/mjones/slots?date=20100104&status=open and not
/slots?doctor=mjones&date=20100104&status=open?

if i am setting up future communications at /slots/1234, to me
/slots?doctor=mjones&date=20100104&status=open makes more sense. would you
typically just have both resources available at those locations?

~~~
rgoddard
Something like depends on the context of the whole application and how you
want to organize it. The first way puts the emphasis on the
/doctors/mjones/... If you have other actions related to doctors like
/doctors/mjones/contact, this way can provide a more coherent organization.
Plus you can extend it to something like /labs/questdiagnostic/mri/slots? So
you can decouple the concept of 'slots' from doctor, allowing you to extend it
to other types of appointments without having to alter slots. The parameters
are the items that are also the most likely to vary. When making an
appointment you will check multiple days, but you are much less likely to
check multiple doctors. Plus the days are more temporal in nature while the
list of doctors is going to stay the same for longer.

------
plq
I kind of expected the XML to disappear in level 3. In its current form, this
is a non-standard extension to HTTP.

