watch these two very good talks on this topic:
* http://oredev.org/2012/sessions/designing-hypermedia-apis
* http://vimeo.com/20781278