Hypermedia Implementation

In the server side

A Restful application should support hypermedia content, and following this constraint, a typical resource representing an order in xml would add controls (links or forms) so clients can navigate through your service protocol (in this case, make a payment):

<order>
	<product>REST training</product>
	<description>REST training</description>
	<price>512.45</price>
	<link rel="self" href="http://www.caelum.com.br/orders/1" />
	<link rel="payment" href="http://www.caelum.com.br/orders/1/payment" />
</order>

Here the order is represented through a typical application/xml file, but it has something extra: controls that allows clients to decide what to do next. Or an example of a valid json representation with hypermedia:

{ "order" : {
		"product" : "rails training",
		"description" : "rest training",
		"price" : "512.45"
		"links" : {
			"link" : { "rel" : "self", "href" : "http://www.caelum.com.br/orders/1"},
			"link" : { "rel" : "payment", "href" : "http://www.caelum.com.br/orders/1/payment"}
		}
	}
}

Last of all, one could add the links on the Link header of the http response:

Link: <http://www.caelum.com.br/orders/1>; rel="self", <http://www.caelum.com.br/orders/1/payment>; rel="payment"

Client side

If you use Restfulie to access such a resource, there will be one entry point and all it's interactions will be driven by hypermedia links:

# retrieves the resource through GET: the entry point
>>> response = Restfulie.at(resource_uri).get()
>>> order = response.resource()

>>> print "Order price is %s" % order.price
512.45

# sends a post request to create a payment
>>> order.links().payment.follow().post(card=4444, amount=order.cost)

# sends a delete request to cancel the order
>>> order.link('self').follow().delete()

This should be all. Requesting the order with the header Accept or the extension xml should get you back a hypermedia supported xml file. With the json and xml versions everything should work accordingly.

By now you should be able to put your resources online and hypermedia-link them whenever they make sense. Do not forget to use hypermedia controls to notify your client the URIs to use for creating and updating content too, as with the payment example above.