Quit pretending

We all have been through it. Whenever some minimal changes are made in your service, all your clients break, and they are already complaining. In other situations, someone else "rest" or web service change, you suffer. It's time for you to complain with them and ask them about moving to a real rest based architecture.

REST is an architectural set of contraints defined by Roy Fielding, from which its usage results in a set of benefits and characteristcs, including higher scalability, fault tolerance, increased security and visibility amongst others: everything the web if capable of offering us, for 'free', without the need to buy or adopt an entire new software stack.

Roy Fielding dissertation

Roy's thesis goes further into what was later called HATEOAS and hypermedia content was understood as another constraint in order to benefit from the web's infrastructure, allowing clients and servers to evolve in a even more loosely coupled way. Hypermedia as the Engine of Application State explained briefly means that hypermedia should guide your client through your server processes. Your client is still aware of what his aim is, but he does not know how to get there. Jim Webber,
Ian Robinson,
Savas Parastatidis.

Based on their upcoming book, Caelum Objects created Restfulie to be one of the first hypermedia-centric frameworks available. It's focuses on hypermedia aware media types allows the benefits from HATEOAS when trying to allow both servers and clients to benefit from a Restful(ie) architecture.

The client code that uses a HATEOAS based system is thought to be the most difficult part to implement. Restfulie provides a client API that focuses on leveraging from HATEOAS benefits by making full use of dynamic bytecode generation (java) or class/object manipulation (ruby on rails).

Why hypermedia?

The following is a typical webservice xml representation using POX, and would be even bigger if it was using SOAP and the WS-* stack:

<%=html '
	sao paulo
	seoul
	2
	1600.00
'%>
	

Any clients consuming this representation should know before hand where to make their payments to. If they want to change the amount of seats, the clients also need to know where to send the new information: all the URIs and fields are known before hand.

There is a coupling between *all* web services that your client is going to access even before it touches the first service (our entry point).

This means that if our service wants to delegate the payment control (or any other part) to a third party payment system, it needs to change all existing clients: the coupling that WS-* stack provides us is nasty.

<h3>ESB?</h3>

Using ESB's would help, while at the same time centralizing control in one place means losing the ability to run clients everywhere on the web. Systems created in 2010 which think they are not going to require clients on the web on the future will have to be updated soon: the web is already our platform.

Knowing URIs before hand is similar to the Service Locator pattern:<br/>

<%= image_tag "service.png", :title => "Service Locator" %><br/>
</p>

<h3>Hypermedia changing the picture?</h3>

The first, but far from last, step is to add hypermedia controls to our representation. In this case, we will add some links:

		<pre>

<%=html ' sao paulo seoul 2 1600.00 '%>

		Since our client's inception, their code is already capable of navigating through those links and whenever those services point to something else, all clients will be capable of adapting themselves with no line of code changed.

		Of course, there is the need to use a common, well known, format: even better, a well known and accepted media type or micro formats.

		Using hypermedia controls to let clients navigate through your service status is to dependency injection as typical webservices (and POX) is to service locator.<br/>

		<%= image_tag "dependency.png", :title => "Dependency Injection" %><br/>

		At this point you have been convinced that hypermedia gives up lesser coupling between consumers and services than typical web services using SOAP and the WS-* stack.
		</p>

Why not URI patterns?

Knowing URI patterns offers the same type of coupling to only one service provider as knowing all URIs. Opensearch is an example of URI patterns that allows service provider to teach clients so the coupling is minimized.