RESTful Web Services Development Checklist
November 1st, 2008 | Published in column, coupling, design, distributed systems, HTTP, REST, services | 14 Comments | Bookmark on Pinboard.in
My Nov./Dec. Internet Computing column is now available. It’s entitled “RESTful Web Services Development Checklist“ and as its name implies, it covers some of the primary areas developers need to focus on to write good RESTful web services. These areas are:
- Resources and their URIs
- Applications and Hypermedia
- Representations and Media Types
- Methods
- Conditional
GET
Regarding the “Applications and Hypermedia” area, I feel Roy Fielding’s pain that many efforts labeled as being RESTful seem to completely ignore the hypermedia constraint. I believe many developers tend to miss this constraint because they’re so used to using libraries and frameworks that offer lots of entry points, and having knowledge of those entry points in the client normally isn’t that bad since the client and library/framework are tightly coupled into the same address space anyway. In a distributed system, though, this definitely does not hold true; when the client knows a bunch of entry points into the service, it ties the client to that service and inhibits their independent evolution.
Anyway, please read the column and let me know what you think, and thanks again to Stefan Tilkov for his helpful review of the draft.
Coincidentally I also feel Roy’s pain when it comes to writing about REST. He states:
I don’t try to tell them exactly what to do because, quite frankly, I don’t have anywhere near enough knowledge of their specific context to make such a decision.
…
So, when you find it hard to understand what I have written, please don’t think of it as talking above your head or just too philosophical to be worth your time. I am writing this way because I think the subject deserves a particular form of precision. Instead, take the time to look up the terms. Think of it as an opportunity to learn something new, not because I said so, but because it will do you some personal good to better understand the depth of our field.
Exactly.
Obviously, Roy is the ultimate REST authority, given that he defined it, so I’m not at all claiming to be anywhere near as authoritative about it as he is, yet I’ve also experienced what he says above. For example, consider this informal review of my columns I received a few months ago in a comment on someone else’s blog:
The articles of yours that I’ve read are…amorphous to me. They speak in generalities. I haven’t read an article where you sit down and write the same service using both REST and RPC and compare the two. When you speak in generalities, we can’t objectively evaluate any of the specific trade-offs between approaches… Arguments that happen at too abstract a level can’t go anywhere, because our positions aren’t specific enough for anyone to evaluate anybody else’s claims.
In other words, “since your columns don’t do my thinking and experimentation for me, they’re useless to me.” Hmm. Maybe I’m just old school, but I’d much rather understand mathematics than require someone to hold my hand while I blindly punch buttons on a calculator. In other words, as the old proverb goes, I’d much rather try to teach you to fish so you can feed yourself. As I state in this new column:
Whether developers of RESTful HTTP-based services write their code in IDEs or with simple text editors, and regardless of which programming languages they use, they must understand REST and HTTP fundamentals to succeed.
November 2nd, 2008 at 1:42 am (#)
Steve, not meaning to be overly blunt, but most people learn new concepts best from examples. Humans are great at seeing patterns in data – even patterns that aren’t there – so presenting several carefully chosen archetypal patterns that, taken together, overlap in the right way to highlight the abstraction, is usually enough.
After that you can start talking about the abstract, when people have a grasp of what it is you’re on about.
It’s best to assume that your audience isn’t lazy or stupid, as you seemed to imply. When the receiver fails to understand, it’s usually a failure in the sender, not the receiver.
November 2nd, 2008 at 2:20 am (#)
@Barry: I don’t disagree that examples can generally be useful, but for this particular topic, I agree completely with what Roy wrote. There’s a time and place for examples, and while I sometimes use them, not every column I publish can or should have them. Often, examples are problematic because they’re too simplistic, or there simply isn’t enough column space to fully explain them and make them worthwhile. Furthermore, the 3-column print format that IC uses is not really conducive to showing code examples, but even if i had the code set into figures spanning multiple columns, what code would I show? Do I write it in Java, or Python, or Perl, or Erlang, or C++, or Tcl? One of each? No matter which language I choose, I leave out other important reader constituencies. And what resource representation media type should I use in my RESTful HTTP examples? HTML? XML? JSON? All of the above, or some other MIME type altogether? For the record, my column word count is typically limited to 2200-2300 words, which works out to be roughly 3 printed pages.
I would never assume my audience is lazy or stupid; if I did, it would be a complete waste of my time to write for them, wouldn’t it? Most people who read my columns seem to appreciate and like them, as I receive a fair bit of email and commentary to that effect. I like to receive constructive criticism, and I get that as well. Based on the feedback I receive, I’d have to say that most of my readers seem very bright and thoughtful. However, I posted that particular review here because it seemed similar to what Roy was experiencing: you try to explain the concepts, which are incredibly important, and some people get on your case because you didn’t do their homework for them. I feel there are already tons of examples available on the web, but what’s lacking is material that boils things down to the fundamental concepts. I think this particular column is worthwhile for RESTful developers because of its focus on the basics.
November 2nd, 2008 at 5:03 pm (#)
I am just curious – do you read the rest of the Internet computing magazine ?
cos I read this article on “BITE – RESTful Composition of services ” (or something like that) in the previous (Sep-Oct) issue and I am really really interested on your views on it (I am concerned I might have become too much of a cynic based upon the reaction I gave to it)
I haven’t had time to read your column but regarding the last line – I am starting to realise that the shift from IDE to text editors is a huge one, not something that you can just quickly pass over. I started off with PHP/Rails and never used .NET/J2EE for much web development. Now when I try to do some web development with ASP.NET I am unable to do so – I find it ridiculously complicated and I just can’t use it – which is funny cos it is supposed to be the easiest thing to make web apps using ASP.NET.
If this is the pain of going from a notepad to IDE, I can’t imagine how hard it must be for people used to living under the weird idiosyncrasies of their particular language – reading the actual RFCs etc. is too much of a pain to them. This is another reason why I particularly agree with your advice for multi-lingual programming.
November 3rd, 2008 at 1:18 pm (#)
Do we need to care about security or is just being a network node good enough to invoke REST Services? Will the RESTafarians start a community fund to pay back customers whose identities are stolen through anonymously accessible REST services?
November 3rd, 2008 at 1:37 pm (#)
@Anonymous: I usually do read the other IC articles, yes, and in fact being on the editorial board and all I even shepherd some of them through the whole publication process. But I somehow missed the one you’re referring to, probably due to my very heavy workload over the past few months. Let me dig it up and check it out.
November 3rd, 2008 at 1:51 pm (#)
@Gunnar: security is an issue for some services but not for all, especially within the enterprise which is what my column mostly focuses on. Over the course of my career I’ve seen many services of the latter variety successfully deployed and used for years.
If you were to pore through everything I’ve ever published, you would find that none of it has ever discussed it security to any meaningful extent. That’s because I’m not a security expert, so I don’t feel qualified to supply advice on that topic. Even the old CORBA book doesn’t go there. Instead, I leave that issue for others who know better than I do, which is one reason why at the end of the column I refer readers to Leonard’s and Sam’s excellent RESTful Web Services book.
November 3rd, 2008 at 2:16 pm (#)
Steve – fair enough. I am all for people knowing their own circle of competence and staying within it.
Let me raise two related points.
1. A lot of what gets written about in development cookbooks and checklists (like Java Petstore) gets copied verbatim and winds up in production apps.
2. The security threats facing distributed computing have increased quite a bit in the last couple of years here is 245 million records breached since Jan 05 (no they are not all directly linked to REST security but you get the point)
http://www.privacyrights.org/ar/ChronDataBreaches.htm
So my ask of software developers especially Web and distributed system developers (which is basically everyone) is to at least clearly state that their are security risks that are not identified in this checklist, cookbook, whatever.
http://1raindrop.typepad.com/1_raindrop/2007/07/doctor-it-hurts.html
November 3rd, 2008 at 2:24 pm (#)
@Gunnar: a point well taken, and I agree that I should have at least mentioned security as an issue. I appreciate your useful feedback.
November 7th, 2008 at 8:01 pm (#)
I think there is at least one case where having “multiple entry points into the system” is irrelevant. Consider a AJAX User Interface. It could ignore HATEOAS and just interact RESTfully with remote services. It can still evolve because it is served up by the server! Then again, I guess you could logically say that Javascript in this case was hypermedia.
November 7th, 2008 at 8:12 pm (#)
I would rather have Roy, yourself, et. al. say a particular API could be “more RESTful” and why, than saying its “not RESTful”. I had the same experiences within the AOP community where pragmatism was just frowned upon.
The thing is, if you can’t call yourself RESTful even though you’re RESTlike, you lose out on a lot of usable vocabulary and implicit understood patterns when describing your API, framework, application, etc. Following me?
For example, saying something like JAX-RS isn’t a RESTful framework because it doesn’t have facilities to easily support HATEOAS is just counterproductive to the whole movement. (I’m not saying you said this, but I’m just giving a for instance…)
November 8th, 2008 at 9:22 pm (#)
@Bill: for your first point, I assume the AJAX app is returned from the server and so is just a case of the code-on-demand REST constraint.
Regarding your second point, I think most REST developers, say those on the rest-discuss list for example, understand that it’s not a black-and-white issue. I think Roy was simply pointing out that people are starting to market services and applications as being RESTful when they’re clearly lacking in that regard.
November 18th, 2008 at 2:19 pm (#)
I once did a presentation on REST. I wanted to share the understanding I gained by asking Roy (after reading his thesis) so many questions that he had the patience to answer. I didn’t claim to be an expert.
I tried to show how Roy derived REST starting from the Null Architectural style and adding constraints one by one and how it induced certain properties and what were the pros and cons. The goal was to create an understanding/appreciation of principled design in general and also on the impact of imposing or relaxing a constraint.
It seemed that most in the audience wanted a quick fix. Very few seemed genuinely interested in understanding the fundamentals behind it. Majority wanted specific examples on how to do a shopping cart etc.. or knowing how they could apply REST to their current environment/project. The following comment I received in my speaker evaluation sort of summerized it.
Maybe I took the wrong approach and was one of those boring types who talks more theory. I am from a math background, and what I learned from a young age is that if you learn the theory/fundamentals behind a concept properly, then you can apply it to any given situation.
November 19th, 2008 at 1:24 am (#)
@Rajith: too bad the speakers can’t do audience evaluations. ;-)
Learning from examples alone is fundamentally flawed. It’s like trying to define the laws of physics based on empirical evidence alone.
One of the best teachers I ever had was a gentleman named Dr. Van Hatz, who taught some of the math courses I took for my BSEE, such as Differential Equations. He began each class with a humorous story of some sort — he was a very well traveled guy and had lots of stories to tell about his trips. He’d then show us the theory of whatever it was he was teaching us that day, and then run through some examples. It was all so clear. If he had shown the examples first, or stuck only to the examples, it wouldn’t have made any sense. Everyone who had to take the courses he taught tried to get into his classes rather than take them from any another teacher, because they all knew they’d have the best chance of learning the material from him.
It’s always best to provide both theory and example if you can, but if you can do only one or the other, due either to space limitations (like my columns) or time limitations (like some presentations), I generally lean toward theory, because that’s the foundation. Like I said in an earlier comment above, it’s usually easy to find examples on the web, so if you understand the theory then you can make sense of the examples, but not necessarily vice versa.
Yes, I know there are people who don’t like this approach — some have already commented here, in fact — but you can’t please everyone.
November 21st, 2008 at 1:47 am (#)
[…] Steve Vinoski – RESTful Web Services Development Checklist […]