The power of hypermedia remains non-obvious

Patrick Mueller contemplates whether or not we really need URIs in our documents1. This is a pretty common question in my experience. This question comes up because it is not always immediately obvious just how powerful embedding links in documents is.

What Mr. Mueller suggests is that if you have a client that needs account information for a particular person that is could simply take the account numbers found in the person representations and based on some out of band information, construct the account URIs. For example, if you got a person representation that looked like

<person>
  <accounts>
    <account><id>3242</id></account>
    <account><id>5523</id></account>
  </accounts>
</person>

The client could then make get requests to http://bank.example/accounts/3242 and http://bank.example/accounts/5523 to get the persons account information. The client would have constructed those URIs based on some configuration or compile time information about the structure of account URIs. This is a very common approach. Hell, it is even the one use by the ActiveResource library in Rails. But common does make it good.

Magically creating URIs out of the ether would work at first but say this bank we work for buys another bank. There are some people that have accounts at both banks. Now, if a persons accounts where referenced by URI, rather than just number, you could just add them to the list like this:

<person>
  <accounts>
    <account href="http://bank.example/accounts/3242"/>
    <account href="http://bank.example/accounts/5523"/>
    <account href="http://other-bank.example/accounts/9823"/>
  </accounts>
</person>

The fact that some accounts are served by the original system and some are served by the other banks system is unimportant. However, if the client is constructing URI based on out of band information this approach fails completely. This is just one example of the sort of problems that disappear when you reference resources by URI, rather than some disembodied id.

One of the potential advantages of using just ids, rather than a URI is that it will require less work on the server to generate the document. I suppose ids are less costly, in a strict sense, if the server generating the document is also serves the account resources. But how much faster? Building a URI like the ones above could be as cheap as a single string concatenation. As far I am concerned, that is not really enough work to spend any time worrying about. On the other hand, if the server generating the document does not also serve the account resources, then the accounts should be being referenced by URI internally anyway so using the URI should be cheaper (not to mention safer).

Mr Mueller suggests, as a proof point, that Google Maps must work by URI construction based on a priori knowledge of the shape of tile URIs. It may well, for all I know, but it certainly would not have to. For example, the server could pass the client a tile URI template and the client could then calculate the x and y offsets of the required tiles based on the x and y values of the tiles it already has. Or each tile could include links to the tiles that touch it (which would allow arbitrary partitioning of the tiles which would be nice). No doubt there are other reasonable RESTful choices too.

The more I work with REST based architectures the more enamored of hypermedia. Links make your representations brightly lit, well connected spaces and that will benefit you application in ways you probably have not even imagined yet.


  1. BTW, Mr Mueller, I was unable to post a comment on your blog. After pressing Post I was brought back to the comments page with the message Comment authentication failed! after the Comments text area.

Comments 2

  1. Patrick Mueller wrote:

    Peter, first, please don’t call me Mr. I’m old, but I’m not … THAT old! :-)

    Sorry about the problem submitting comments; there have been some problems with comments at dWorks in the last few days.

    Note I’m not discounting links; I’m suggesting they don’t have to be presented as URLs on the wire. In fact, your Google Maps sample of the server sending a URL template … just another case of the data story; the client will end up taking the data and deriving the final URL. In that case, from the template. In my example, from some a priori knowledge of the layout of the URLs in the system.

    The “link as data” scheme clearly only works for a “closed system” in which the layout of the URL space is known in advance by the client, or communicated in some other fashion (URL template). Not appropriate everywhere. Didn’t mean to imply it would be.

    Posted 12 Oct 2007 at 2:06 pm
  2. Peter Williams wrote:

    Patrick,

    No offense intended with the Mr bit. I don’t generally call people I have never meet by their first names (unless of course I am invited to do so).

    As for the subject at hand, I think that data at URI even for closed systems is less than optimal. It really locks you into what ever the current way of thinking about your system is. You could use a URI template, I suppose, a way around that problem. But to allow for future changes to the system you would really need to include the URI template with every response and seems like a lot for effort to avoid generating the URIs server side.

    Posted 12 Oct 2007 at 3:16 pm