Nobody Understands REST or HTTP (opens in new tab)

The biggest problem with today's REST implementations is that they're essentially a database serialization layer. Consider how a RESTful Rails model is typically represented as:

  {
     book: {
        id:1,
        name:"To Kill a Mocking Bird",
        author_id:2
     }
  }

How do you get more info on the author if you only have this piece of information? Rails/ActiveResource guesses through convention: "/authors/2", but that might not be the case, which makes this approach very brittle.

A better more "RESTful" approach might be:

  {
     book: {
        href:"/books/1",
        name:"To Kill a Mocking Bird",
        author: {
           href:"/authors/2"
        }
     }
  }

The REST client would then be able to traverse the representation without making guesses at the URL, and if the end-point of '/authors:id' changes for whatever reason, the href would be updated accordingly.

Pagination/large data-sets could be solved as well:

  {
     books: [
        href:"/books/1",
        name:"To Kill a Mocking Bird",
        author: {
           href:"/authors/2"
        }
     }
    ],
    rel: {
       prev: "/books?page=1",
       next:"/books?page=3"
    }
  }

... and a bajillion other common RESTful API problems through better convention.

I'd agree with the author that REST is misunderstood, but my opinion is that its misunderstood on the grounds that today's "REST" implementations are lame database serializations. The web has been doing this since the <a href/> tag was conceived, but for some reason, modern REST implementations left this out.

Is there any way to make the browser do an Accept: application/csv header on a hyperlink?

I'm pretty sure users like their "Download as CSV" links, which I've generally done as /normal/resource/url(.csv)

While this post sets out the ideals, I think there are some cases where for usability, you have to do something less than ideal.

I had a really interesting conversation about this with a coworker a few weeks ago. We were talking about URL design. I argued for URLs like this:

  /networks/
  /networks/girl_talk/
  /networks/girl_talk/tracks/
  /search?term=bass&sort=artist

He argued for URLs like this (note the pluralization):

  /networks/
  /network/girl_talk/
  /network/girl_talk/tracks/
  /search/bass/sort/artist/

My case boiled down to, “A URL represents the path to a resource. You should be able to remove any number of parts from the end of a URL and be left with a different, meaningful URL. In the case of search, the terms are options that describe what you want returned by the search, not resources.”

His case boiled down to, “A URL is a sentence. You should be able to read a URL as English and get a good idea of what it represents. In the case of search, adding more path components adds words to the sentence to make the search more specific.”

He pointed out (paraphrasing) that URLs are a language — and languages evolve. URLs as paths better embodies the RFC, but a new style of URL might be more meaningful on today’s (and tomorrow’s) web.

Very good read, and thorough. I particularly like the transaction example. It seems like a common idiom that trips people up with REST.

However, I do have a problem with REST that I've been dealing with lately. Specifically, the question of web-hooks. Many services today allow you to pass a URL that they will hit with a POST request whenever something happens. A good example is the GitHub post-receive hook (http://help.github.com/post-receive-hooks/). So, to be a good student of REST, I create an /update resource for the POST (similar to the /transaction example from the article). However, /updates might come in a variety of formats. Not just JSON vs XML, but GitHub vs Gitorious vs Beanstalk vs etc.

So, how do I handle these "formats". Presumably the "Accept" header is out of the question (unless the provider happened to know about MIME's vendor extensions and used them). So then is it acceptable to add a parameter? Use "/update?from=GitHub" for example? Or, is it appropriate to use an extra path element like "/update/GitHub", since the resource really is a "GitHub update", not just a vanilla "update"?

I thought I finally had REST figured out until I read this.

Does anyone else see a diminishing return on pedantically following the REST-prescribed design and actually creating an API that people are familiar with out of the gate? I feel like if I followed this article to the T in my current design, anyone trying to integrate with it would spend so much time reading my API documentation just to figure out why they weren't getting an XML reply that it would stop being productive.

I am working on an API for imgscalr right now and I think I have it about 80% RESTful at the moment -- the parts I'm not doing is paying any attention to the headers either coming or going between client or server.

I'm using the more recent "classic" /path/object.{format}?arguments format that I have seen folks like Wordnik and Vimeo use.

It may not be purely RESTful, but it is intuitive and I can't help but think: "Remember 3-4 years ago when REST wasn't all the craze and no one knew what it was? The web still managed to function back then..."

I'm trying to mix some practicality in a bowl filled with "best practices" and come up with something that most people can stomach.

I hope I hit that mark, but we'll see. As far as I'm concerned I'm sticking with the versioned URLs because I find it more intuitive for endpoints that change, get renamed or are removed than slamming one inside of a mime type or header or even a query string param a la AWS.

I read the post and I have to say that he's got a nice flamebait title but totally avoided the thorny issues that people argue about. In fact, I'd like to be pointed to a solution for the following problems:

1. I'm an old Web programmer, and my introduction to the Web started with HTML, not HTTP. I don't just write APIs, I write Web apps. I find it difficult to explain to people what this means:

    <form action="/some/noun" method="POST">

If you are religiously RESTful, you probably think this is fine. But I'm a religious English reader. When I see the word "action", I think of a verb, not a noun. When I see the word "method", I think of "how", not "what". So when I look at the HTTP spec, all the HTTP "verb"s look to me like how-I-should-do-something, instead of what-to-do, and the resources (URLs) look to me like the what-to-do, instead of what-they-represent.

Small semantics issues I suppose, but here's another one:

2. HTTP is not a programming language, and yet it demands a (very) finite set of actions and an infinite set of objects to model the real world, where there are an infinite number of actions and objects. What I mean is, in Java or whatever OOP language, I can define classes to model objects and define methods in classes to model actions on objects, but I'm not sure if I can do it pragmatically in HTTP without getting yelled at.

3. HTTP statuses. Almost the same problem as the above. I have many different kinds of statuses, not all of them fit in the finite set of HTTP statuses, and they don't always provide the granularity I want. Can I return a non-standard status number? How would the clients behave? I have no idea.

4. Being RESTful means not being stateful. But you see, there's this thing called session and login cookies and many other tracking cookies that I have to take care of. Again, I don't just write APIs, I write Web apps. I would like to not do multiple handshake requests just because a paper says I should. I would also like to not get yelled at when I decide not to.

5. HTTP is RESTful, thus HTTP is REST. Please don't tell me HTTP is the best we can do. Can I have something more minimalist, extensible and powerful enough to model the real world?

-- A troubled Web dev.

good article but...he says version numbers in the url are bad but doesn't say why. using accept headers for versioning is a hassle for every client and makes browser based testing much more difficult. also a v1 user really might not be the same as a v2 user so they shouldn't be the same resource.

The problem with posts like these is that they say things like "THIS IS BAD!!!!!1" without saying why.

This is an excellent example of a spec being deemed more important than a useable system.

Frankly, I don't give a damn about the REST spec, and neither should you. When I see an API I want it to be simple and clear.

/getAllPages/

Hey, it's a verb and I've got a pretty good idea of what I'm going to get back

/getAllPageNames/returnType/JSON

Now I really know what I'm getting. The simplicity and usability of this structure absolutely trumps a spec compliant call that involves request headers and nouns.

If you're building a system that requires having read someones dissertation, you're not doing us any favors. Especially when it comes to an API. Keep it simple, stupid.

Remember that your understanding of what a URL 'is' or 'should be' comes from a great deal of technical experience. If you're not working day in and day out to make powerful tools accessible to people WITHOUT such experience, please stop programming. Really, get out of the pool. Whatever awesome knowledge you need to make a system work internally is invaluable, but your interfaces should make the world a simpler, more magical place.

I've personally given up trying to save the term REST. It was hijacked and will never recover completely at this point. What I've been looking for is a good alternative name. Sometimes I'll write out representational state transfer which is clever enough to get past most REST pretenders but I have yet to find something short.

I don't think that I can fully agree with the idea that a news article written in English is not different content from the German version.

I don't understand the point of "uri":"/transactions/1". Isn't the new resource's URI already part of the response (in the Location: header)? It's sort of like saying GET /posts/show/1 vs. GET /posts/1.

This is a great article. One challenge I am facing now is both building a RESTful API, along with a UI that uses the API. The biggest question I have is the use of shebangs in urls with the ajaxy app. We must support IE so pushState is out, but shebang just seems like a hack. I think at this point I have no choice but to implement shebang but I wonder if there are any viable alternatives?

Rest was a really big deal in the Java web-app world for about a year...

It was back when early versions of Struts were 'the designated alternative', and in the bad old days of J2EE and JAX-RPC.

Then Java EE 5 came out, which solved large chunks of the pain that J2EE inflicted, JAX-RPC got replaced with the infinitely better JAX-WS and there was a new breed of web frameworks as well, which blew Struts out of the water.

About that time REST essentially became 'yesterdays technology, solving yesterdays problems'.

I find it interesting that the guy banging the REST drum is a Ruby fan. Has REST always been part of Rails? Or is it something that has crept in over the last couple of years?

Is there anything genuinely new here, or is it the same old story, some dude clinging desperately to an obsolete technology?

Some of this feels like trying too hard to adhere to HTTP. For example,

> Accept: application/vnd.steveklabnik-v2+json

This declaration loses information, because it no longer contains the MIME type for JSON in a standardized format. Assuming the server responds with the same string for Content-Type, any application that does not know specifically about this API can no longer recognize that it's JSON and, e.g., pretty-print it for a user, as I haven't seen done for JSON but is regularly done for XML by browsers.

On the other hand, the original suggestion:

> Accept: application/json

works in theory, but in practice makes it more difficult to test the API in a browser. This is not the end of the world, but there does not seem to be any real benefit in using Accept. I cannot think of any practical situation where a tool can use the standardized header for an advantage...

While I generally agree with the principles underlined in the article, using the Accept-Language header is definitely not the right way to control internationalization.

Remember that one of the advantages of URLs is the ability to easily share them, however I'm not sure I'd be comfortable sharing content that could show up translated to some recipients, based on the language of their browser/application/computer. For example, most CMS systems assume that the content can be completely different between languages (for the same article): you can have the full text in English and only a teaser in other languages.

Maybe not a pure REST approach but using '/en','/pt','/fr' in the URL has proven to be much easier and safer, from my experience.

Content Negotiation is a critical part of REST APIs and it's my observation that most simply ignore or default to JSON in all cases. Good REST APIs allow the client to "choose" the mime type. Without this part of REST - you have no "representational".

On that topic, to rely on an 'Accept' header is pretty risky. That presumes the client will always have control over the headers. It is in my opinion always wiser to make the API determine mime type by extension (.html, .xml, .json etc).

I've had this discussion about hundred times now. REST "standards" are as important and significant as brace indentation "standards". A big problem with REST is that it is NOT a canonical (or even important) standard, but rather a useful pattern than can be used to make things exposed via HTTP more intuitive. The evil side effect of this is that a metric crapton of architects/engineers are wasting fifty bajillion programming-hours arguing irrelevant details about who's doing it "right" instead of building useful software. You cannot do REST "wrong" and more than you can do software "wrong"... Folks who argue about the "right" way of doing software are usually "wrong" because they are focused on writing software instead of solving problems.

We need to keep our priorities straight.

I really dislike creating resources to represent transient actions. Not a big deal in the case of a bank transaction as that is something you could easily imagine needing to be stored for later retrieval. A different example is relating one social network friend to another or searching for specific people on the site. Those are things that, to me, are much more borderline and I would err on the side of not representing them as resources.

The title seems rather sensational. Is that really necessary?

He's right, but older web developers might remember the alternative, which was having no design pattern at all.

Most web developers aren't going to read the computer science papers about REST, and how strictly you want to adhere to it, depends on you, and your development team. It's a design pattern, or a tool, but it's not a religion.

On that note, I've gone into several job interviews where they ask me to explain what REST is, and I always start with, "REST stands for Representational State Transfer...", at which point, I get the feeling that the interviewer wasn't aware of that, and I wind up telling them way more about REST than I think they wanted to know.

Here's something I've observed:

i) most successful "RESTful" APIs don't really follow all the REST principles (e.g Flickr, Amazon, Dropbox). My thumb rule is this: If an API does not start from a "mother" URI that gives you the most updated list of resources that can then be requested by the application, it is not really HATEOAS.

ii) a purely resource-oriented view of your entire API space shoehorns you into doing really strange things to keep REST "purity"

So my conclusion is that using an architecture/concept originally intended for humans navigating hypermedia documents may not be a natural fit for parts of your API that cannot be modeled as such. See the Dropbox REST API documentation (http://www.dropbox.com/developers/docs#api-specification) (" Section: Deviations From Standard REST Style") to see an example of the pragmatic decisions taken.

A very good and comprehensive writing.

One thing that I cannot find mentioned neither in the article nor in comments, is the confusion related to the idea of state.

While REST is, by definition, stateless, it merely describes the session, not the manipulated data. There's no way to avoid, at least implicit, object's state. For example, if user's password is not empty, it means that the user already set the password.

More comprehensively, with /users/1/edit, or whatever, it is frequently expected to get a different validation error, depending on the flow, such as a paid account might require more billing related details than one without email confirmed.

Of course, it is a nightmare to maintain such matters implicitly. That's why Ruby on Rails plugins like acts_as_machine, and similar, come handy. They do provide an explicit description of the object's behaviour, easy to transform into documentation, depending on the current state.

The idea shows its full potential with multipage forms. Each step of the form might be described with a different state, stored in the state attribute, leaving the controller RESTful, and the model's validations easy to understand.

A yet another confusion comes with too close database mapping. To stick with Ruby on Rails, there is nothing preventing the developer from creating his own setters and getters, like def vattr=(); end; def vattrr(); end.

The framework passes the value of a virtual attribute, using params, to #update_attribute, and other methods, the same way it does for regular attributes created automatically from the database's schema.

Very frequently such attribute provides a much cleaner way to represent the model, rendering either the HTML or the API much more easier to write or understand.

If nobody understands REST, and as other articles have claimed, nobody does it right, then why do we keep trying to use it? Switch to something simple that everyone can understand like JSON-RPC and quit worrying about pedantry.

Excellent article... We followed all of these Rest principals when we designed apis for HP cloud print (i think it will soon become public)..except

1) Representing all resources with noun - We had a tough time representing all resources with Noun. One of our APIs is Post on \PrintJobs\ - creates a new print job

But printing can only start when all the data (content to be printed) is uploaded on the server. So client needed an API to tell the server that it can start printing..something like this..

\printjobs\1\print \printjobs\1\cancel

one way we thought to avoid this was to have a represent it job state and client can change them like this..

\printjobs\1 Put : <job> <state="print"> </job>

But there are cons

1. These were not actually states, these were actions(verbs)..because state would be initialized, printing etc.. so if client does Get after making it Put..it will get "printing" not "Print".

So we were tangling with keeping semantics clear and making it easy at the same time. Hence we went with these resources. Do you think it could modeled better?

2) When we think of versioning, we always assume that only the representation can be changed..why not behavior? Take for e.g. if api implementation changes but not representation..clients may be dependent upon the implementation (i know this is bad! since implementation details are getting leaked out from the API)

Thoughts?

You can't satisfy the HATEOAS constraint by simply returning URLs in the JSON response from your API. The structure of the data is still tightly coupled to your own application, and so must be any client that can make use of it.

It is essential that RESTful applications be able to evolve independently from the client. To allow this, they must use forms of hypermedia generic enough to serve as the engine for all present and future versions of the application. If the client has any code specific to your app, then your app is not RESTful in any scope beyond its own.

I'm not convinced that the whole resource vs action thing is all that important to REST. It's an ideal that has been largely ignored in practice and the web has been quite successful without it. Contrast this with HATEOAS which has been the unavoidable reality of the web since day one.

I've been working with/learning about Webmachine lately. A really nice framework for building REST APIs.

It really is a good read, I need to digest it, but my initial reaction is that some of this isn't pragmatic. Versions in URLs makes for dead-simple routing in any framework. Also, many APIs are used in a way where you know consumers will create a resource without requesting it (or at least, not within the same session). So why return any location information (whether in a header or in the body)?

Ironic that the author's homepage (http://steveklabnik.com/) is a confusing pretend console that takes several seconds (on every visit!) to reveal useful information.

REST is great and all, but browsers don't allow it. The only thing you can do is GET, nothing else is supported cross-domain.

No matter your thoughts on REST, it's dead. It's never happening. This argument has gone nowhere for 10 years.

Very few if any websites conform to the spec, and browsers have made it impossible to do so.