RESTfulie - A Gem To Create Hypermedia Aware Services And Clients

Guilherme Silveira writes to InfoQ on the release of a ruby gem that makes developing hypermedia aware services and clients that consume them a breeze. He said

Much has been spoken about what is and what are the advantages of using rest/restful ideas in one's application. Last year, Mark Baker wrote about hypermedia content in restful applications. There are also a few texts on more formal attempts to define HATEOAS and its advantages. Although being some good usage of the web in order to create web-based services, it is still missing the very best part of our every day life: hyperlinks and hypermedia content.

He goes on to describe an example of defining an order that goes through a well defined set of transitions for e.g. from example from unpaid to paid etc. It also allows the mapping of various transitions to a corresponding actions...

class Order < ActiveRecord::Base 
  state :unpaid, :allow => [:latest, :pay, :cancel]
  state :cancelled, :allow => :latest

  transition :latest, {:action => :show}
  transition :cancel, {:action => :destroy}, :cancelled
  transition :pay, {}, :preparing 
end

Which generates, for example, an atom based resource representation that has embedded hypermedia:

<order> 
   <product>basic rails course</product> 
   <product>RESTful training</product> 
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" 
          href="http://www.caelum.com.br/orders/1" rel="latest" /> 
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" 
          href="http://www.caelum.com.br/orders/1/pay" rel="pay" /> 
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" 
          href="http://www.caelum.com.br/orders/1" rel="cancel" /> 
</order> 

And allowing the client to invoke dynamically created methods from consuming that resource representation:

order = Order.from_web 'http://caelum.com.br/orders/1' 
order.pay(payment) 

Jim Webber, on whose RESTBucks article and forthcoming REST book has been inspiration for the creation of this gem, said

The mulit-talented Guilherme Silveira with Adriano Almeida and Lucas Cavalcanti, has been coding up a storm on the RESTful services front. [...] More importantly, they’ve written up a generic client that can be used to explore that protocol. They’re hosting the demo service on GAE, and have released their code for all to enjoy on GitHub. Fabulous work guys, and very timely too

Savas Parastatidis, the co-author of the book had the following comment

I can’t wait for our book to finish so that everyone can check out our discussion of hypermedia and the stuff we’ve built. It’s really great to see Restfulie taking a very similar approach to ours.

Detailed examples of the gem usage for creating RESTful services and clients that consume those services are available at the GitHub project repository.