We’ve been adding RESTful interfaces to an existing distributed app to give it some much-needed scriptability.  I was able to cook up a client very easily in Ruby, using URI templates to describe the server API.  This approach got us up and running nice and quickly and I was happy enough with it, but I would have been happier still if it didn’t feel so, well, homebrewed.

Among my readings on REST and answering some of my concerns over our app’s discoverability, this very interesting post from Dare Obasanjo on REST API Design pointed me to the XRD initiative.  It’s covered in multiple posts on the excellent Hueniverse, of which this XRD Sneak-Peek is a good place to start.

XRD seems to have everything I’m looking for in a standardised web API description but for this one issue: given multiple templates that map to resources of the same type, how do I choose the the one most appropriate to the the set of parameters I have in my client?  For example, my blog might support two:

  http://positiveincline.com/articles/{slug}

http://positiveincline.com?p={id}

Having the server prioritise these (as provided for in XRD) makes no sense in this instance; the client needs to be able to choose.  How about then have some way of marking template variables as mandatory, like {+slug} perhaps?  Thoughts, anyone?

Back to Ruby meanwhile, may I recommend sporkmonger’s Addressable gem, an improved URI class with template support.  My first foray into open source contribution resulted with a minor fix to it being accepted today.  Thanks to the amazing github, this transaction was concluded in a matter of minutes!

All of this is one step along the way towards a new gem (tentatively “path-to”, registered on rubyforge) which will make it very easy to describe web applications on the client side in Ruby, and later to support discovery mechanisms such as XRD.  There are some corporate hoops to jump through before I can take this further, so watch this space.

P.S. XRD gives me hope that URI templates might still be “officially” alive, despite the expiry of the draft 3 spec.  Is there anyone out there making this so?  A lot of googling and trawling through w3c archives later and I’m still not sure.