It’s just data

Progressive Disclosure

Roy Fielding: I am getting frustrated by the number of people calling any HTTP-based interface a REST API.

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


Hey, you managed to squeeze a whole book valiantly trying to decipher Roy’s thesis :)

Posted by Paul Downey at

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.

Posted by Sam Ruby at

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.

Posted by Ian McKellar at

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.

Posted by Sam Ruby at

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.

Tim-

Posted by Tim Ewald at

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.

Posted by Sam Ruby at

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.

Tim-

Posted by Tim Ewald at

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.

Posted by Sam Ruby at

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]

Trackback from Lost Boy

at

Specialization

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

Excerpt from Untangled at

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.

Posted by John Calcote at

Holding back the waves?

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

Excerpt from Applied Life at

Getting RESTive

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

Excerpt from business|bytes|genes|molecules at

The DNA Network

h1 a:hover {background-color:#888;color:#fff ! important;} div#emailbody table#itemcontentlist tr td div ul { list-style-type:square; padding-left:1em; } div#emailbody table#itemcontentlist tr td div blockquote { padding-left:6px; border-left: 6px...

Excerpt from agribusiness at

Pragmatic message about REST

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

Excerpt from Open IONA Combined Blogs at

Ted Neward does come to a similar conclusion about the limits of what you can/cannot do with REST: [link]

Posted by Dilip at

RESTful REST

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

Excerpt from Ragnarok Studio at

It's NOT a RESTful API

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

Excerpt from New York Java Consultant at

[from jaz] Sam Ruby: Progressive Disclosure

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

Excerpt from Delicious/network/pkeane at

[from alan.dean] Progressive Disclosure

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

Excerpt from Delicious/url/a642b0d60d991446db0d251cee297fdd at

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

Excerpt from Lost Boy at

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

Excerpt from Dion Hinchcliffe's Blog - Musings and Ruminations on Building Great Systems at

WSDL - first, CXF JAXRS model - first !

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

Excerpt from Musings about web services at

Add your comment