
Common REST Mistakes - pan69
http://www.prescod.net/rest/mistakes
======
idlewords
Several of these points are highly prescriptive without offering any
motivation for the advice.

For example, "your public API should not depend on the structure of your URIs.
Instead there would typically be a single XML file that points to the
components of your service." It's difficult to understand this kind of point
without an example in hand - preferably an example taken from an actual
website.

The whole list presupposes a familiarity with REST theory and jargon. And the
assertion that 'sessions are irrelevant' instantly raises my suspicions about
the author's relationship with reality.

~~~
tlack
I agree. A lot of the more pedantic REST advocates seem to use this kind of
thinking, such as implying that we shouldn't use descriptive URIs because the
client or programmer shouldn't need to understand how the URIs are structured.
If that's the case, surely we could break REST convention as much as we want
and just make the programmer or client go along with it.

I think when most normal people say REST, they simply mean some sort of vague
messages-over-HTTP metaformat that doesn't necessarily enforce odd
restrictions about POST vs. PUT, is somewhat self-documenting and easy to work
with due to the limited scope of the medium, etc.

~~~
derefr
I don't think it was implied that we _shouldn't_ use descriptive URIs—just
that descriptive URIs should be treated in roughly the way we treat
comments—they're for humans to work with, not computers, _unless_ there is an
established microformat (like the various -Doc formats used in comments) that
the service can be guaranteed to obey. That microformat would, obviously, be
linked to in place of the index XML file—as it would be able to be used to
procedurally generate same.

------
angelbob
Point 3 is phrased well in the title, but I'm kind of annoyed at the
implication that you should intentionally obscure your URLs. I can see why he
makes that point, and I see the benefit, but I also like URLs that make sense
when I'm cutting and pasting.

I have a much easier time finding a cut-and-paste error from email in
<http://bob.com/posts/37/comments/79> than in
<http://bob.com/postthing/1f724c302a3b69ef9327313adb269a8d>, even if the
latter is convenient when the site later restructures things or adds a server.

------
telemachos
Since a number of people have mentioned point #6 (Sessions are irrelevant), I
have a question: Can anyone point to a concrete, more detailed discussion of
_how_ to do authentication and authorization in a RESTful manner?

I may be missing something very obvious, but I just don't see how this
should/can/might look. (Just to be explicit, I'm not trolling. I'm confused.)

~~~
derefr
Basically,
[http://en.wikipedia.org/wiki/Digest_access_authentication#Ex...](http://en.wikipedia.org/wiki/Digest_access_authentication#Example_with_explanation)
but with anything you like in place of the GET.

~~~
kmt
Is the well known and used cookie based authentication in conflict with REST?
In my mind it's not, it's orthogonal to it.

If not logged in, redirect to a login page (resource) which upon success
redirects back, e.g. GET login?next=desired_resource.

If logged in but not authorized to perform the action on the resource return
401.

That's it basically, isn't it? Also not trolling, challenge me if I'm missing
something please.

~~~
daredevildave
Cookie-based authentication is generally only applicable to the browser
interface. From my point of view where REST really shines is at the API level.
HTTP authentication while not particularly great in the browser ( mainly
because of UI/logging out issues ) is good at the API level where you send
your credentials with each request.

~~~
derefr
> HTTP authentication while not particularly great in the browser ( mainly
> because of UI/logging out issues )

You know, with all the little browser-chrome experiments that have been going
on lately, I'm really surprised that no one has tried to make HTTP-
authentication-based login/logout/account management as painless as HTML-
served variants. I'd imagine that it would couple with the little "lock" icon
in the URL/status bar, making it have four states instead of two: "insecure,
secure, insecurely logged in, and securely logged in" where clicking on it
brings up a menu to both view credentials and change your password/edit
profile/log out/close account/sign up/anything else browser makers want to
implement. (They could be distinct, of course, but I like the idea of making
"insecure" look scary so that users would be deterred from sending credentials
through it.

------
ratsbane
Point 6 (Sessions are Irrelevant) is really tricky. Fielding says much the
same about sessions as this article but there's a lot of room for
clarification.

<http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>

~~~
kmt
My take on "sessions are irrelevant" is that you don't start and close a
session. You start by creating a resource: itenerary, document, submission or
whatever you call it. You do that by POST-ing to the list of such resources
and you edit it (PUT) until you're done. You could always come back to it
(GET) and edit some more (PUT). Or you could delete it (DELETE).

Of course, there can be authentication and authorization but, really, there's
no need for a session since you have to do those two on each http request
anyway.

------
petercooper
I believe #3 is actually a cornerstone of modern Ruby on Rails usage :-)

~~~
sabat
I have not read Roy Fielding's dissertation, and so I am speaking out of
partial ignorance. But isn't most of this the opposite of what REST is
supposed to be? URLs aren't supposed to represent resources? Whahh?

~~~
blasdel
The contents of URL strings are not supposed to represent resources -- If a
client of your "REST API" needs to concatenate strings together to form new
URLs based on an out-of-band 'specification', _YOU'RE DOING IT WRONG_

Repeat after me: Hypertext. Is. The. Engine. Of. Application. State.

URL strings should be completely opaque -- you should be finding link to new
resources in other resources, not constructing them yourself (query strings
added to found resources are permitted).

The whole "meaningful URL" thing is a strong signal of False REST, and it
infects the Rails ecosystem pervasively. REST has nothing to do with your oh-
so-clever request routing rules.

~~~
generalk
One can build a service that has so-called "Rails-style meaningful URIs" that
also returns hyperlinks to new resources. They aren't mutually exclusive.

That said, yes, everyone seems to forget about hypertext. I'm curious: if I'm
building a REST-based JSON-formatted service, what's the convention for
returning related URIs? Ex: if I return a Product resource andi want to have
links to the products image, the owner's resource, edit this product, and so
on, is there a standard way to return them in the JSON structure, or doesthis
nor matter?

------
wanderr
REST has always felt a little bit dirty to me; an improper commingling of what
should be two different layers. To me, using aspects of the HTTP protocol to
have meaning for a higher level service is a bit like using aspects of the TCP
protocol as part of the HTTP definition, where in a more ideal setup they
should be independent, but layered on top of one another. Almost all of the
REST mistakes mentioned in this article are due to the unholy matrimony of the
two layers, and the misunderstandings and abuses that arise from that.
Additionally, using HTTP error codes can break compatibility for anything
running in a browser plugin (i.e. Flash) because the browser eats the error
code and does not pass it on to the plugin. Needless to say, I'm a big fan of
RPC which runs over HTTP POST normally but isn't married to the underlying
protocol. I think SOAP gives RPC a bad name (I certainly hate the crap out of
it) and doesn't properly separate the protocols either, using HTTP codes to
indicate errors and such.

~~~
kmt
I think you might be wrong about the 'underlying protocol'. HTTP is an
application layer protocol. If something feels dirty it is to put another
protocol on top of it especially if it doesn't add value.

With REST, you are not adding more special meaning than the HTTP methods.
Using those methods according to the spec is all there is to it. If that's
enough to do your business, why add more to it? Things should be simple as
much as possible.

~~~
wanderr
Simplicity is good, but so is flexibility and compatibility. As I mentioned,
parts of REST aren't good enough; anything that doesn't have access to http
status codes won't be fully compatible. A decent RPC protocol like JSON-RPC is
both flexible and simple. An added bonus to not marrying your protocol to http
is that your API will work seamlessly over other protocols should the need
arise. I have an API that was originally intended for web clients, but later
the need arose for some internal tools to be able to call the same methods
remotely and asyncronously. Instead of going over http, the jobs are submitted
to gearman in JSON-RPC format and everything works without having to modify
the server or unnecessarily and inefficiently route the calls externally
through apache.

~~~
kls
I used to argue in favor of json-rpc as well, but I have to say that I have
allied with the dark side now. if for no other reason than caching, with REST
you have fine control over what addressable resources get cached and which do
not. This is huge for performance in some systems. I have found once you use
REST semantics in earnest to build an application, it is hard to levy argument
against it. So much of the webs infrastructure starts to work with you and not
against you once you start to use it.

~~~
wanderr
It's possible my perspective is skewed. I write APIs for stateful
applications, so clients don't ask for the same information over and over,
reducing the need/utility of browser caching. I can see how REST would help
solve the caching problem.

------
wooster
Point 6 (Sessions are irrelevant) is where REST really falls down as a way of
explaining the success or practical operation of the web.

------
scdlbx
What REST actually is, is not explained on this page. More information can be
found here: <http://en.wikipedia.org/wiki/Representational_State_Transfer>

~~~
johns
Better explanation: <http://tomayko.com/writings/rest-to-my-wife>

------
phaedrus
I'm actually designing a REST system to connect together the subsystems of a
robot with a number of independent microcontrollers, so this is very relevant.
Keep the REST articles coming, please!

------
petewarden
He lost me at 'use PUT and DELETE'. There's a whole range of clients (eg most
browser's XMLHttpRequests, Flash) that don't support anything but GET and
POST.

~~~
Plugawy
Not true, XHR allows to use DELETE and PUT without any problems.

But yes - Flash can only use POST and GET (or maybe only POST? It's been quite
a long time since I used Action script)

~~~
ratsbane
I think he means HTML forms. PUT and DELETE are broken in at least some (even
modern) browser implementations.

