RESTful coding standards

In AJAX Considered Harmful Sam Ruby starts to lay out a set of useful coding standards for REST. He addresses Encoding and Idempotency, however going a little further has helped me. I have tried to apply the KISS principal and be a minimalist i.e. only add layers of complexity when you need them

Most use cases I have come across can be reduced to a CRUD interface (and yes there are exceptions, and exceptions prove the rule). The starting point is some standard naming conventions to create some degree of consistency for users for example:

• Create POST to http://xml.domain.com/resource/Create


• Read GET from http://xml.domain.com/resource?QueryString


• Update POST to http://xml.domain.com/resource/Update


• Delete POST to http://xml.domain.com/resource/Delete

The other issue is how to pass arguments and results back and forth. Some decisions are obvious, GET always passes a query string and the return data is always XML both using UTF8. I always have issues with POST though for invocations I recommend using XML always as it is hard on a user to have to switch between POST form parameters and XML for different methods. If XML is always used it keeps everything consistent. However when a delete method only requires a single key it is very tempting to just pass form parameter or even just do a GET with a query string. So far I have stayed with consistency - I would be interested in other opinions.

The other of standardization that helps is error returns, SOAP Faults are a good idea that REST can easily adopt. With a CRUD interface there are a simple set of standard errors that can be defined that come back with a HTTP 500 status code:

• Create: Item Already Exists User has no permissions ...


• Read: Item Does not Exist User has no permissions ....


• Update: Item Does not Exist Item Locked User has no permissions ...


• Delete: Item Does not Exist Item Locked User has no permissions ....

A simple REST Fault schema can be used to always return the same format such that common utility code can be created to handle errors in a uniform way. For errors to return permissions errors there needs to be the idea of identity which requires authentication

For authentication the lowest common denominator seems to work most of the time - interested to hear about real cases where it does not. If the request is over HTTPS and the authentication is HTTP-Auth then we have pretty good security. One step further would be to PGP the message but that would only be needed where the message needed to be highly secure and it traveled over unsecured pipes before and/or beyond the HTTPS stream.

I would be interested in feedback and extensions to this as it would be nice to have a consistent pattern for programming REST interfaces. The consistent pattern would enable us all to build interfaces faster and learn to use the work of others faster and easier.

Laszlo has released 3.0b2

This release is a big milestone for OpenLaszlo (IMHO) as it provides for serverless deployment of the UI components. Obviously a server is still required if you need to interact with data but not for rendering. After working with systems such as Dreamfactory the importance of not needing a server for rendering became very clear both for simplicity of deployment and scalability. Congratulations to the OpenLazlo team for taking things in this direction

Nelson on actual implementation of SOAP and REST

Phil Windley posts from ETech: Phil Windley's Technometria Nelson Minar at the Google AdWords API. This is good summary by Nelson Minar on the issues and differences around implementing services in SOAP and REST. I particularly like Low REST and High REST definitions - a good characterization I have been struggling how to explain and rationalize in an implementation for the last few weeks.

For REST to come into its own there needs to be some more formalism along the lines that Nelson suggests and also so does David Orchard.