« Buddycrap | Main | Presentation Logic and Django Templates »

REST design notes

Brian Repko's Blog: Ain't gettin' no rest with REST:

"One really bad way to do it is to leave it up to the client. For a Void, the client does a GET, changes state to void and then POSTs the updated version. For a Reverse, the client does a GET, changes state to REVERSE, creates the reversal, PUTs the reversal and POSTs the original with its state changed. Ok, that clearly will not work so we know it has to be done on the server, so what URI represents this method call. I got a couple of ways to do it and am looking for thoughts on these designs."

If you use GET to obtain the state of the resource, you subject yourself to the whims of caches and proxies on the chain. POST at least brings your request back to the origin server (or your web farm). GET might not proceed further than a browser cache.

"The first way to do this is to make URIs for the methods as well as the properties of your domain. So if you have a "void()" or "reverse()" method, then you could have the following URIs that you would POST to."

Designing to REST says you should send the state of the resource to the server, not ping resource proxies. Orthodox web applications would tend to use PUT.

The fundamental problem here is looking for a RESTful way to do RPC/RMI, instead of redesigning the application to expose resources. In RPC, you send the name of the operation, which is domain specific, either to a service/controller, or perhaps to the actual object you want to affect. The REST way is to send the state of the resource using a fixed set of methods - the methods are all your application can use to affect or determine state. These approaches are not easily reconciled, as has been demonstrated over and over, notably with XML-RPC and early SOAP RPC encoded styles. That's because the RPC style over HTTP means using HTTP methods as tunnels for the domain specific calls. So, this leads to modeling and design issues, but also affects scalability and security. No intermediate HTTP aware system understands your private defined function calls, their caching or security implications.

Typically POST is used for RPC. This can lead people to erroneously conclude that POST is the prime method in HTTP, going as far as standardizing around it. Two, maybe three generations of object oriented programmers have walked into that trap. Don't do that!

If hiding state is a key design constraint for you (often the case in OO designs), the idea of exposing state using representations might feel broken. Good REST designs as they appear in HTTP are all about encapsulating implementation, both the physical details and the private application; details (like "void()"), that aren't assured to globally interoperate. Encapsulating state is not really a design goal.

An exception to all this resource-orientation might be things that are truly 'services' - activity based matters, like searching, imaging, geolocating. In those cases it can be useful to model the call as being into a coordinate space and not just a private method taking arguments.

"The last thing - and probably the topic of the next entry is the need for meta-data for the representation - and in particular how to do versioning for optimistic locking operations - the classic read-read-write-write problem."

For this, look at how Etags function. And watch what happens around Atompub as it get used for content management systems. Also how Subversion implements transactional submits over WebDAV is instructive.

The above was written on 2006-08-07. Since then I've seen some posts that suggest REST style is only suitable for simple things, but not non-simple things like transactions; for that you need real systems design. Maybe, but I belive some (not all) not these positions are about pre-assuming a solution. When you supply examples (like Subversion commits) simple appears to get redefined. My suspicion is that "non-simple" here is like the old saw about "artificial intelligence" - once you solve an AI problem, it ceases to be an artificial intelligence problem.

August 20, 2007 06:53 AM

Trackback Pings

TrackBack URL for this entry: