Nobody Understands REST or HTTP

This was posted 7 months ago on HN (with 510 points!): <a href="http://news.ycombinator.com/item?id=2724488" rel="nofollow">http://news.ycombinator.com/item?id=2724488</a><p>Very lengthy discussion at that time.

The part about "accept-language" doesn't address the real problem. If I copy the url to a piece of content that is available in 2 languages and send it to someone else, I want them to read it in the same language as I originally read it. Sadly, I cannot copy Accept-Headers in a fashion that "normal" people understand. To me, resources written in 2 different languages may be instances of the same thing, but not the same resource.<p>At worst, the page in question uses automatic translation (not so uncommon when it comes to large knowledge bases), so the translation might be odd.<p>Basically, according to the article, Wikipedia has it all wrong.

There are numerous opinions on the subject of RESTful apis. The author of this post makes many good points, but I, like many of you disagree with his opinion on versioning.<p>While putting the version into the header is clever, it reduces the usability of your api. When you are designing a RESTful api you typically want to design your api so that it is simple and easy to implement. Nothing is easier than being able to explore an api via a web browser. If you make the user specify versions in the header than they will have to install a browser plugin to explore your api.<p>You have to consider that you aren't always "selling" to other developers who understand http headers. You could be "selling" to non technical project managers and CEOs who simply don't understand http headers. They do understand URIs, though. So if you can provide these people with a URI that just works, and they can poke around and see data they have a greater chance of understanding and getting excited about your API.

This says versioning in the URI is wrong. Why? I much prefer separating my API versions into different files at the dispatcher level. Doing it with the header would be a mess in most frameworks, and I don't see what it hurts.<p>Also, what about custom HTTP verbs? Many times I need something more than GET/PUT/POST/DELETE. What happens then? I haven't seen anyone talk about that.

Interesting. But it has one flaw; how exactly would I do this<p>curl <a href="https://api.twilio.com/2010-04-01/Accounts" rel="nofollow">https://api.twilio.com/2010-04-01/Accounts</a> -H "Accept: application/json<p>inside a browser on a normal GET request?

A lot of good points there, but the part about detecting mobile devices is a bit short sighted.<p>Varying your content based on mobile User-Agent (or any User-Agent actually) renders public caches almost impossible to get right.

Thanks so much for saying what needed to be said :)!<p>David Zülke has a very good talk about REST that he's holding at conferences around the world regularly: <a href="http://www.slideshare.net/Wombert/designing-http-interfaces-and-restful-web-services-phpday11-20110514" rel="nofollow">http://www.slideshare.net/Wombert/designing-http-interfaces-...</a>.

This webinar by Brian Mulloy is a nice complement to the post and offers up some great design tips when it comes to designing a RESTful API...<p><a href="http://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_webinar/" rel="nofollow">http://blog.apigee.com/detail/slides_for_restful_api_design_...</a>

For more resources on this topic, I have been leafing through O'Reilly's Hypermedia APIs book, it's been interesting.

He didn't go over the common example of paging by including<p><pre><code> nav { prev: '...', next: '....'} </code></pre> in the response. But, the thing that always concerns me about this is that it requires the client to maintain state. If you consume such a web service in a web app, and the user hits "next", you'll have to have stored the next url somewhere.

If I want to raise my blood pressure into the 180's all I have to do is open a thread about web design "principles".<p>He has the perfect anti-example for HATEOAS right in there: financial transactions. You would never in 1 million years want to discover the API for such a thing by experimentation, because there are specific precision requirements.<p>Every time someone tries to explain the benefits of this nonsense to me it's either 1) something you could already do with sockets 20+ years ago, or 2) a poorly motivated academic idea that doesn't get me closer to implementing a correct system with good documentation.