While I don’t really have much to add, here is what I have...
Without intending to take anything away from Roy’s (valid) criticism on labeling, REST isn’t an all or nothing proposition. One can get significant value from partial adoption.
One can only go so far by studying HTTP. Hypertext links are more a characteristic of HTML than of HTTP. Similarly, Code on Demand is a characteristic of the combination of HTML and JavaScript than of HTTP.
Hey, you managed to squeeze a whole book valiantly trying to decipher Roy’s thesis :)
Co-authored. And Leonard did the bulk of the work.
And the end result didn’t do enough justice to hypertext or code-on-demand. Still, many have found it to be useful. Which is the point of the title of this post.
There are some pretty bad offenders - people who proudly talk about their REST which just turn out to be RPC calls with the method name and parameters tossed into the URL.
First of all this kind of API is harder to implement correctly than something like XML-RPC or SOAP because you’ve got to roll your serializer and parser from scratch - which is prone to errors (for example, are you serializing non-ASCII characters correctly?). Secondly they often disregard GET’s defined impotency (thought Last.fm claims not to).
I think it’s good that people are making their APIs available via HTTP, but I wish people wouldn’t use the acronyms HTTP and REST interchangeably when describing APIs.
Yes, there exist bad offenders. Ones that make no use of GET at all. Or worse - make use of GET for non-idempotent actions. Those APIs are neither good examples of HTTP nor particularly RESTful.
The API that Roy is critiquing is not one of those bad offenders. It is the product of the result of learning the first wave of lessons. It makes appropriate use of GET, POST, PUT, and DELETE.
This API represents a new class of design error. One that makes good use of HTTP, but isn’t as fully RESTful as it could be.
I read Roy’s post with interest because I’ve been evangelizing the hyperlinking model (inspired by you Sam) for the past 18 months. It’s been interesting trying to get people to understand and embrace this approach. Too many APIs, and frameworks (e.g., ActiveResource) require shared knowledge of link formats to work correctly.
I think there are two stumbling blocks for people with this approach. First, what format should their representations. As you mention, links are really part of HTML, not HTTP. But the Web wouldn’t be the Web without them, so I agree with Roy that they are a critical component of RESTful design. So we need a representation format that supports links (and forms?) like HTML does. I’ve used two models: a slimmed down XHTML (built according to the spec’s modularization guidelines) and a simple XML format based on Atom/Record/Sequence with links and forms built in. Other models are of course possible. We need some reasonably (de facto) standard way to do this.
The second stumbling block was mentioned in an earlier comment: lack of support for serializing and parsing. This one confounds me. We don’t lack support for that, it’s built into every major MVC framework out there. It just isn’t the same set of tools we used with SOAP (or at least not assembled quite the same way).
We have to figure out how to get past these issues to support the linking model because it is really key to helping developers understand how to implement more complex processes through REST. If you think about the shopping process on Amazon, you really count on links to lead you through it. The same approach can work for software, but too often APIs focus on manipulating individual entities to achieve an overall affect, without anything other than external knowledge to stitch those steps together.
Every MVC framework certainly has support for serializing... but for parsing? Not so much.
That’s why I’m so interested in things like HTML5 and JQuery. Both are designed for coping with the types of output that MVC frameworks produce. I see JQuery (a.k.a. CSS selectors) as having the potential to be slightly easier to use and a bit more resilient than XPath.
The work that really needs to be done is to generalize XML. No, I’m not talking about the petty squabbles between that other Tim and Arnaud, but to take the parsing work in HTML5 and generalize it.
If I had infinite resources, I’d love to pull Ian off of HTML5 for a brief period and ask him to design a successor to Atom. One where the content isn’t “tunnelled” over the carrier wave that is the feed format by escaping, but instead one where consistent rules were followed for matching tags and recovering from errors. I think everybody would learn a lot from that exercise.
P.S. Amazon cheats and uses sessions/cookies; as does pretty much everybody in this space. That does impact scalability, but that can be solved in other ways. What is important is that it keeps coupling down. A similar mechanism, even as imperfect one as cookies, is required for any generalized solution.
I agree that there is work to be done on the parsing side. If it were generalized to XML, do you imagine a standard way to do hyperlinking in XML or just sticking with XHTML(5) as the premier entity body type for programmatic services?
I agree that Amazon uses sessions and cookies. It isn’t clear that they have to do it that way, but it is damn convenient. As you not in RWS, if the session data is not kept on the server but is encoded in a cookie (as is the default in Rails 2), you alleviate some of the issues. Also, if we’re talking about programmatic clients that may not have back buttons, I’m not sure how much of an issue it really is.
xlink is a standard; but for harvesting purposes it may make sense to be inclusive and snarf up things like a/@href, xhtml:link/@href, atom:link/@href, and the like. If you are into triples, RDFa provides lots of data.
I think we are in sync on the notion of cookies, but just to make sure, I’ll recap. Cookies need not be either a scalability or a coupling issue; but for cookies to work at all, the client needs to know to look out for them, and to produce them on demand. That’s not at all the default today with non-browser based clients.
Explaing REST and Hypertext: Spam-E the Spam Cleaning Robot
I’m going to add to Sam Ruby’s amusement and throw in my attempt to explicate some of Roy Fielding’s recent discussion of what makes an API RESTful. If you’ve not read the post and all the comments then I encourage you to do so: there’s some great tidbits in there that have certainly given me pause for thought. The following attempts to illustrate my understanding of interaction with a RESTful system. Perhaps bizarrely, I’ve chosen to focus more on the client than on the design of the server, what resources it exposes, etc. This is because I don’t think enough...
[more]
As you may have noted, my last post seems to have hit a nerve in various communities, particularly with those who are convinced that REST means HTTP (because, well, that’s what they think it means) and that any attempt by me to describe REST...
It’s true that hyperlinks are related to HTML, but hyperlinks are also a generalization of the more generic link references defined by hypermedia. HTML is only one form of hypermedia. I believe one of Roy’s key points here is about hypermedia, not hypertext.
Roy has spoken . Paul , Dave and others have attempted to interpret. Unfortunately, there are many who don’t have time to listen, are not interested in listening, or do not possess the necessary understanding. For those people: REST is not SOAP...
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Those words come from the man who put REST on the map, one Roy Fielding in a bit of a rant against what people call REST today. The post is worth reading...
Sam Ruby says in his Progressive Disclosure post : “Without intending to take anything away from Roys (valid) criticism on labeling, REST isnt an all or nothing proposition. One can get significant value from partial adoption.” IMHO this message is...
… And why expression is the most important thing of all human beings. 最近一些重要的API继续着把REST和HTTP-based等同起来的错误倾向，终于激怒了Web标准专家、REST概念的提出者Roy Fielding博士，并将他的不满用一篇blog表达出来，就是最近非常热的这篇 “REST APIs must be...
If you’re using a RESTful API, chances are that it doesn’t meet Roy Fielding ‘s defintion of REST , because it doesn’t meet the Hypermedia As The Engine Of Application State (HATEOAS - pronounced either “hideous” or "hate yo’ ass") constraints as...
Without intending to take anything away from Roy’s (valid) criticism on labeling, REST isn’t an all or nothing proposition. One can get significant value from partial adoption....
I am amused by the people who are valiantly trying to decipher Roy. While I don’t really have much to add, here is what I have... Without intending to take anything away from Roy’s (valid) criticism on labeling, REST isn’t an all or nothing...
Explaining REST and Hypertext: Spam-E the Spam Cleaning Robot
I’m going to add to Sam Ruby’s amusement and throw in my attempt to explicate some of Roy Fielding’s recent discussion of what makes an API RESTful. If you’ve not read the post and all the comments then I encourage you to do so: there’s some great...
Can We REST For A Minute? 6 Lessons From The CRUD vs. Hypermedia Debates
Recently InfoQ did a good summary of the debates around the apparent (to some) limitations of REST when it comes to creating good Web services. At issue is that REST APIs seem to expose “CRUDy” services that fly in the face of years of good...
So you’re a SOAP developer who prefers starting the development of a new service from creating a WSDL document first. It is a WSDL-first approach that works for you, not a Java-first one. You are also interested in giving it a try and seeing what...