Using the web infrastructure

Some recent posts here and at our company’s blog were dealing on how to use the web as an infrastructure for distributing an algorithm, but this post is related to how to supply a service or resource based system using some of the web infrastructure.

Last year, at Falando em Java 2009, Jim Webberr spoke about HATEOAS, Microformats and how hipermedia content could add to a servicing system.

Based on his upcoming book and some of the ideas presented on his blog, I have created a small project with the help of Adriano Almeida and Lucas Cavalcanti at Caelum to help others explore some of those topics in a easy way.

Two simple projects show off what hypermedia content can do to simple resource/service based applications.

The server application is responsible for a small and simple ordering system where one:

1. sends an order (post)
2. requests it’s status (get)
3. sends an update (post)
4. cancel it (delete)
5. pay it (post)

Actions 3-5 are made available through action 2: by getting the resource representation, one can parse it and find its available actions – leaving it to a human-programmed software to request the next step in its flow or, for those who see flow automation as a good thing, for an automatic generic client to decide whats the next step.

The client application is responsible for being a “generic client”. But a generic client can be something harmful too so its one designed for those users who want to test their servers and learn how those resources work.

In order to try out the applications, you can use the google app engine infrastructure and follow the steps below:

Entry Point

Every resource/service based application has a single or set of entry points. From the point of view that such integrated systems should be programmed by humans (and not entirely automated), the consumer application should be aware of the entry point and its http verb, therefore:

Access http://restful-client.appspot.com/ and try to post an order to:
a) entry point: http://restful-server.appspot.com/order
b) method: POST
c) name: content
d) content: any order content (it will not be validated)

This is a well-known entry point and both client and server application are aware and agreed on that. By following that mindset, one will have a set of those entry points that are aware for both sides.

Those who look for fully automated services or systems will probably create a single starting point containing a GET request which results in the set of former entry points.

Running the consumer application

PAY ATTENTION: you might need to run it twice when you first run it. google app engine has a slow startup time that
might run a timeout prior to succeeding.

After posting the order, you will receive a 201 response with your order location.

You can then view (GET) this order to see its representation. By parsing the representation, one can discover what you can do with your order:

– pay (request a payment POST)
– cancel (request an order DELETE)
– update (request an order UPDATE)
– view (request an order GET)

Anytime you can check your order status by getting it. After payment your status will change to PREPARING and after one minute it will be DONE. If you cancel your order, it will be CANCELED.

While the client application is mostly a javascript+html view of what is being consumed, it still contains some vraptor serving our requests. This way we were forced to visualize for the first time how can we generalize a little bit the idea so we create a somehow generic consumer library in Java.

At the same time, a ruby version of the server side library supporting services-aware-resources will be released here soon. The java version is also being built around vraptor already. The next step is to build a ruby library – due to its dynamic nature, one can create really nice resource representations on the client side of what we just received from the server.

Those interested in helping us are welcome to mail me.
Although its a simple server application, it is a good way to show how to use the web as an infrastructure in a little bit more than the (rest-non-ful) CRUD examples found on the web.