In a comment on my previous post, pwb states

"REST" still suffers mightily from no real guidance on how exactly to construct something REST-ful. A dissertation doesn't cut it.

I guess it depends on what is meant by "real guidance". I can argue that there is no real guidance on how to construct object oriented systems, distributed applications or high performance data storage systems. Whether you agree or disagree with any of those statements depends on how "official" or "canonical" one expects such guidance to be.

If you are interested in building RESTful Web services. Here are the top 3 ways I suggest one learn about building and designing a RESTful system. 

  1. Learn the Atom Publishing Protocol: The best way to figure out how to build a RESTFul Web service is to actually use a well designed one and none is a better example of what a RESTful Web service should be than the Atom Publishing Protocol. For extra credit, you should also read up on Google's GData protocol and come up with a list of pros and cons of the approaches they've taken to extending AtomPub.

  2. Read Joe Gregorio's "Restful Web" column on Joe Gregorio is one of the editors of RFC 5023 (the Atom Publishing protocol) and is currently employed at Google working to make GData even more Web friendly. He started a series of articles on on building and designing RESTFul Web services complete with code samples. The entire list of articles can be found here but if you don't have the time to read them all, I suggest starting with How to Create a REST Protocol which covers the four decisions you must make as part of the design process for your service 

    • What are the URIs? [Ed note - This is actually  "What are the resources?" ]
    • What's the format?
    • What methods are supported at each URI?
    • What status codes could be returned?

    If you have more time I suggest following that article up with Constructing or Traversing URIs? which contrasts client access models based on URI construction [where clients have baked into them knowledge of the URI structure of your service] or by URI traversal [where clients discover resources by following links either within the primary resources your service returns or via a service document that describes your service's end points]. Just because WSDL is a disaster doesn't mean that interface definition languages aren't useful or that they aren't needed in RESTful applications. Afterall even Atom has service documents

    And finally, because I don't believe you get to design a system without being familiar with what the code looks like and should do, I'd suggest reading Dispatching in a REST Protocol Application which walks through what the server side code for a particular RESTful service looks like. He even throws in some performance optimizations at the end.

    Of course, I know you're actually going to read all the articles in the series because you're a dutiful lil' Web head and not shortcut seeker. Right? :)

  3. Buy "RESTful Web Services" by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson:  If you are the kind of person who prefers to have a book than learning from "a bunch of free articles on the Internet" then RESTful Web Services is for you. I haven't read the book but have seen it on the desks of more co-workers than I'd care to admit and each of them favorably recommended it.  Sam Ruby, Leonard Richardson and DHH know their stuff so you'll be learning at the feet of gurus. 

To me, this seems like an abundance of resources for learning about building RESTful Web services. Now I understand that there are some for whom until it shows up on MSDN, IBM Developer Works or in a Gartner Report it might as well not exist. To these people all I can say is that "It must be great to have all that free time now that you have outsourced your thinking and business critical analysis to someone else". :)  


Monday, November 19, 2007 5:02:12 PM (GMT Standard Time, UTC+00:00)
Is an O'Reilly book good enough?

Personally, I haven't found that my consulting customers need much help with REST, because it's what their developers do by default if no one sends them out for WS training -- just a few words hints about best practices for URLs, GET, and POST, and they're ready to rumble. Like M. Jourdain in Molière's Bourgeois Gentilhomme, they're excited to find out that what they've been doing all along actually has a name.
Monday, November 19, 2007 5:08:18 PM (GMT Standard Time, UTC+00:00)
OK, thank you.

David, I don't think it's quite that easy as most of what people come up with is not considered very RESTful (I'm referring to public APIs such as Amazon, eBay, PayPal and all the Web 2.0 stuff). One question I would have is, what would the Amazon/eBay/PayPal/etc APIs look like if they conformed more closely to REST?
Monday, November 19, 2007 7:27:14 PM (GMT Standard Time, UTC+00:00)

I haven't read the O'Reilly book, so you might want to check some reviews before ordering.

Fieldings' dissertation and some of the RESTafarian writings make REST harder than necessary (who really uses PUT or DELETE, and why do you have to learn words like "idempotence"?). Here's my own take on what actually matters:

Monday, November 19, 2007 10:11:26 PM (GMT Standard Time, UTC+00:00)
David, yes, thanks. I apparently did read that (and commented on one of my outstanding questions: are querystrings really that bad?).

Agree that POST and GET are sufficient (and that they should be used properly).

I'm still not clear on a few thigns:
+ Basic authentication adequate?
+ Best way to represent arrays?
+ If I'm doing say, payment processing, do I really return a URL in the location such as ? Can I also provide a paramter in the repsonse txn=972346583465 ?
Tuesday, November 20, 2007 1:15:09 AM (GMT Standard Time, UTC+00:00)
RESTful Web Services is by Leonard Richardson and Sam Ruby. DHH wrote the Foreword, but was not an author.
Comments are closed.