Common 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.

[derefr]

By "sessions are irrelevant", he basically means "don't recreate circuit switching on top of your packet-switched TCP/IP connection." Each HTTP request should carry with it all the state required to do what it needs to do (including state stored in cookies et all); it shouldn't be dependant on what has come before or what will come after it.

[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.

[Vitaly]

the idea is that instead of documenting your project list to be at /projects/ and individual projects to be at /projects/PROJECT_ID you should have a SINGLE entry point into your API which should have LINKS to your various services.

so you will have something like

    <api>
      <projects>http://../projects/</projects>
      </users>http://../users</users>
    </api>

or even this:

    <service>
      <name>projects</name>
      <href>http://.../projects/</href>
    </service>
    ...

and then your project list should not just return you projects ids to construct a url with, instead it should provide you full urls to access the relevant resources.

The rule of thumb is: with a PROPER REST API you should never do any "url generation", you should get ALL your urls (except for the SINGLE entry one) form the API.

check out this link for some more info: http://www.theamazingrando.com/blog/?p=107

[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.)

[carpo]

One way to do this is to have the clients pass the authentication information in the headers with every request.

[derefr]

Basically, http://en.wikipedia.org/wiki/Digest_access_authentication#Ex... but with anything you like in place of the GET.

[steveklabnik]

If you know Ruby, you could check out AuthLogic.

[gthank]

The HTTP spec includes the Basic and Digest methods of auth.

[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?

[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.

[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)