

REST isn't what you think it is, and that's OK - renaebair
http://intridea.com/2010/4/29/rest-isnt-what-you-think-it-is

======
bradgessler
The problem with a lot of REST framework implementations, like Rails, is that
it acts as nothing more than a database record serializer/deserializer. A
vanilla Rails resource looks something like this:

    
    
      <post>
        <id>1</id>
        <title>This is a post</title>
        <comments></comments>
        <author_id>100</author_id>
      </post>
      

When you consume this resource, you end up having to munging database foreign
key IDs into an URL string. For example, if I want more data about the author
of the post above, I'd have to grab <author_id/> and plug into another
endpoint, like /authors/:author_id. Who knows if /authors is the correct
endpoint? Even if it was, if that endpoint changes, it could break the URLs
that I munged together.

These "RESTful" implementations should really look like is the following:

    
    
      <post href="/posts/1">
        <id>1</id>
        <title>This is a post</title>
        <comments href="/posts/1/comments"/>
        <author href="/authors/100"/>
      </post>
    

Given such a format, I don't have to guess what the endpoints are for
associated resources; I just look at the href and grab the resource if I want
it.

A collection could include dataset navigation information, such as:

    
    
      <posts>
        <link rel="prev" href="/posts/?start_id=51&items=50"/>
        <link rel="next" href="/posts/?start_id=101&items=50"/>
        <post href="/posts/1">
          <id>1</id>
          <title>This is a post</title>
          <comments href="/posts/1/comments"/>
          <author href="/authors/100"/>
        </post>
        <!-- more posts here... -->
      </posts>
      

Now I can implement a less breakable client that doesn't need to munge URL
endpoints with database foreign keys. Furthermore, I can navigate through
datasets by following the <link rel/> tags.

~~~
bmason
The only thing I'd do differently here is put the comments and author links as
<link rel/> tags as well. No reason not to standardize the representation of
links. Optionally you could list inline the entire contents of the sub-
resources. Doc types should allow composition in this way and it allows you as
a designer to reduce unnecessary traffic and latency.

------
bmason
This article doesn't really clarify things for me. I agree that not many APIs
in the wild right now are truly RESTful, but this has been stated for years.
We know this. The article then posits that true REST is too hard. This is
simply not true when you look at the bigger picture. Yes, it may be easier in
the moment to cowboy it up and reinvent the wheel, but when it comes to
maintaining your service and integrating it with others, you pay the price for
lack of foresight.

The questions that need to be answered are how would true REST be different,
and why would I want to spend my precious time learning about it and
implementing it?

This is a pretty good one stop shop for the first question:
[http://www.nordsc.com/ext/classification_of_http_based_apis....](http://www.nordsc.com/ext/classification_of_http_based_apis.html)

Martin Fowler's article on the subject is good too:
[http://martinfowler.com/articles/richardsonMaturityModel.htm...](http://martinfowler.com/articles/richardsonMaturityModel.html)

And this article shows a basic "hello world" implementation of REST, and
explains the benefits: <http://www.infoq.com/articles/subbu-allamaraju-rest>

I appreciate the author's enthusiasm towards REST, but I would prefer to
discuss the technical merits rather than engage in justification and
categorization of what's out there right now. Yeah, it's not REST, and yeah
people are going to call it REST anyway in certain contexts. But in the
context of architectural design we have clear definitions about what REST is,
and there's no need to muddy the waters.

------
LiveTheDream
Facebook OpenGraph API has a discoverability feature like the one from the
article; add "metadata=1" to the query string of a resource and you get a list
of connections included in the information. For example, look at
<http://graph.facebook.com/btaylor> then
<http://graph.facebook.com/btaylor?metadata=1>

------
vinhboy
I was following, until I got this "No out-of-band knowledge should, therefore,
be required beyond understanding a media type that the resource can provide.
From there, it should be possible to follow relations provided in “hypertext”
context of the representation to “transfer state”, follow relations, or
perform any necessary actions." -- can someone translate that? I don't
understand it.

~~~
loup-vaillant
Out-of-band knowledge is prior knowledge. Typically file formats or protocol
specifications (whether they are standardized or not, widely used or not).

The first sentence of your quote say that all prior knowledge should be about
media formats (like the html specification, microformats, the PNG image
format…).

From there, the medium itself should provide enough clue for the client to go
on. For instance, anchor links in html says you can GET a resource at the
specified URI. Other media formats could provide other clues.

To sum up, the only things you can specify a-priori are media formats. URIs
and protocols should be interchangeable, so you can update and deprecate them.
I think the main goal of REST is to concentrate coupling on media formats
alone. Hopefully, most media formats are (or will be) standardized,
effectively _reducing_ coupling. Basically, REST architectures are for the
long term.

~~~
DougWebb
Also, a URL for the root of your service should be sufficient to find every
resource that the service provides access to, and every method that can be
used with those resources. The example is a website; from the home page of a
website you can reach every other page of the website by navigating through
hyperlinks and form submissions.

Another example drawn from the article: if the blog posting service provides
each post under a uri like /posts/{post-id}, the client of the service
shouldn't have to know the uri structure. Instead, /posts/ should be a
resource, and it should contain hyperlinks to all of the /posts/{post-id} uris
that are available. There would probably be some metadata about each one as
well, such as a title, to enable clients to figure out which one they want to
follow.

------
mikek85
Actually, I think the REST community is pretty clear on this now - there's no
need need to accept incorrect definitions, omitting the hypertext constraint
is not REST. "While the true definition is interesting for academic purposes
and certainly lies behind the technologies upon which we build every day, it
simply doesn’t have a whole lot of use to web application developers" - this
is missing the point a bit.. If you're developing web apps for humans the
reason REST 'doesn't have a use' is because it's already been 'used' to
produce HTTP and HTML. "Doing REST" is essentially the process of designing
hypermedia types, and defining/extending a uniform interface. Examples of that
would be writing the AtomPub spec or reintroducing Link headers.

------
kennu
I think understanding "true REST" is an excellent starting point and guideline
for any API designer. But also trying to follow it too rigidly, at the cost of
performance and complexity, is unwise. I believe the article came to the same
conclusion.

------
10ren
It's partial adoption.

Instead of RESTful, why not the more accurate RESTy or RESTish? Because it
doesn't sound good.

~~~
lftl
"High REST" vs. "Low REST" was one bit of vocabulary that was bounced around
for awhile:

<http://lesscode.org/2006/03/19/high-low-rest/>

------
oceanician
I've seen Jim Webber give some very good talks on REST.
<http://jim.webber.name> Think he's got a book coming soon on it..might be out
even?

------
IgorPartola
I was under the impression that HTTP was only a one example of RESTful system.
The OP suggests that HTTP verbs must be used to interact with a RESTful API.

~~~
DougWebb
Uniform methods are an important aspect of a RESTful system, just as important
as Uniform Resource Identifiers. The client of the system has to know what the
methods are, so if you define your own methods you put a burden on clients to
implement those methods in order to use your service. HTTP provides a set of
methods that are sufficient for most RESTful services, and the methods in HTTP
are widely implemented in existing libraries. Base your service on HTTP's
methods and you've enabled a huge number of clients to use your service.

------
apphacker
I care about REST because I remember SOAP and I am very happy that REST mostly
won that war, at least in the public API space. I suppose there's something to
his article about diverging from the idea of resource definitions but I hope
that API providers stick to REST as closely as possible and don't do things
such as require cookies in their API or have the app manage state some other
non-RESTFUL way that isn't simply passing a token as a POST or GET value for
example.

~~~
mbleigh
I never meant to imply that I don't LIKE REST-like APIs on the web. Holy
opposite day, Batman, I think they're fabulous! It's really just an
exploration of the ways in which the popular definition of REST diverge from
the actual definition, and what we can learn from the original definition to
make our REST-like APIs all the better.

~~~
mikek85
Yes people have tended to miss out the hypermedia constraint and claim to be
REST - partly because everyone's been too excited about using HTTP properly to
think about anything else, but also just because there's been a lack of
tooling and guidelines for designing media types properly. Most people in the
REST community agree on that point and now there are useful approaches and
technology emerging - restfulie is a great example of this.

------
Sujan
REST was new for me a month ago. Then I read lots of books, even more articles
and played with every REST(ful) API I could get my hands on.

And I came to the exactly same conclusions. Couldn't you have written this 4
weeks earlier?

