javascript_basic

Hypermedia representations

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 xmlns:atom="http://www.w3.org/2005/Atom">
	<product>rails training</product>
	<description>REST training</description>
	<price>512.45</price>price>
	<atom:link rel="self" href="http://www.caelum.com.br/orders/1" />
	<atom: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;

console.log("Order price is #{order.price}");

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.