REST worst practices. A few weeks ago, I sent the following in a email to a co-worker asking for input on designing REST APIs in Django.
Since then, I’ve quoted myself a few times; I thought these thoughts would be worth a (slightly edited) public home. I think the best way to dive in terms of mistakes to avoid. If you poke around you’ll find a couple-three different stabs at writing a generic REST API module for Django. So, with no further ado, some REST “worst practices:” Conflating models and resources In the REST world, the resource is key, and it’s really tempting to simply look at a Django model and make a direct link between resources and models – one model, one resource.
I’d solve this in a similar manner to the way forms work in Django: there’s a basic Form, and then a ModelForm; I’d have a Resource and a ModelResource. Hardcoded auth (Or depending on cookie-based auth.) Resource-specific output formats The idea is that client code shouldn’t have to know how to parse all sorts of different formats. Why REST and SOAP Composition Models are so Different. There's a mini-controversy going on over the importance of hyperlinks, and whether they're only usable by humans.
Jonathan Marsh seems to think that hyperlinks are less useful for machine-to-machine interaction. The REST viewpoint seems to be that services without hyperlinks "dead-end" the Web, hence the absence of solid support for links in SOAP is a further argument against its usefulness. I have (as usual) a different viewpoint on this altogether. I think SOAP and REST are duals. They both model the Universe of Discourse, but in different ways. It would be silly to disparage REST for being silent on "process", just as it would be silly to accuse SOAP of "dead-ending" services from a namespace perspective.
REST resources are composable in Namespace (to form content). The S stands for Simple. There has been a long running debate in the Application Platform Services Group here at Burton Group between the REST people on one side and the SOAP people on the other.
For the most part it mirrors the external debate. In one recent exchange, while discussing the complexity of SOAP and the web services framework, the SOAP side said, “Before all of the WS-* stuff, SOAP was actually simple. That’s what the ‘S’ stood for.” And now a history lesson. It’s the year 2000, a harried developer has a problem Developer: So, my boss was playing golf this weekend, and now I have to ‘quote, unquote’ SOAP-enable the enterprise, but I don’t know what SOAP is. SOAP Guy: Sure thing. Dev: So it’s simple? SG: Simple as Sunday, my friend. Dev: Okay, lay it on me. SG: Well, just like it says in the name, SOAP is used for accessing remote objects. Dev: Like CORBA? SG: Exactly like CORBA, only simpler.
Scalable Reliable Secure REST. RestWiki. Richardson Maturity Model. A model (developed by Leonard Richardson) that breaks down the principal elements of a REST approach into three steps.
These introduce resources, http verbs, and hypermedia controls. Recently I've been reading drafts of Rest In Practice : a book that a couple of my colleagues have been working on. Their aim is to explain how to use Restful web services to handle many of the integration problems that enterprises face. At the heart of the book is the notion that the web is an existence proof of a massively scalable distributed system that works really well, and we can take ideas from that to build integrated systems more easily. Figure 1: Steps toward REST To help explain the specific properties of a web-style system, the authors use a model of restful maturity that was developed by Leonard Richardson and explained at a QCon talk. Level 0 The starting point for the model is using HTTP as a transport system for remote interactions, but without using any of the mechanisms of the web. Resource-oriented vs. activity-oriented Web services. Caelum's restfulie at master.