Wednesday, April 21, 2010

Hypermedia constraint check

The Hypermedia Constraint seems to be the toughest one for developers to "get" in a RESTful system.  Most of my architecture documentation/communication effort has been focused on those things that one needs to get it right.  Things like: links in representations, link relations, etc.  Still, all too often, folks get it wrong.  Terribly wrong even.  So, I've thought about a simple check that I could provide as the hint that you're "doing it wrong":

Imagine the URLs to all resources except the static bookmark had a variable number of random numbers somewhere in the path and changed on each request.  Would your client still work?  Would your service's documentation still be correct?

Is it possible to answer yes to both questions and still break the hypermedia constraint?


  1. I don't think so. Do you have any suggestions on changing documentation from "links in representations" and "link relations" to something which makes users of the system "get" it? I'm thinking of providing a working example client application to show them how it's supposed to be done.

  2. Not really, in my case, I'm using xhtml as a "service descriptor" that serves at the bookmark URI. I write, tutorial style, an explanation of initial resources available - providing hyperlinks with proper relations. Consumers of the service can read it and software can 'read' the same page. I also give some simple pseudo code that provides an example of how one might move through the system, making link selections based on rel values. One of the beauties of using xhtml as the representation is that it allows me to include this narrative inline with the service resources.