There’s a really nice RFC out that defines the concept of a Link header.  Link headers are like Atom links within documents except they are specified within request or response headers.  For example let’s say we wanted to GET a medical image of an MRI.  This image might have additional relationships to a front, back, top, bottom up view.  A response with link headers might look like this:

HTTP/1.1 200, OK
Content-Type: image/jpeg
Link: <http:/.../front.jpeg>; rel=front; type="image/jpeg",<http://.../back.jpeg>; rel=back;type="image/jpeg"

...

The jpeg format cannot embed hyperlinks within it so to obtain relationship information, the Link header is used.  Other than data formats that don’t support hyperlinks, using the Link header can also be very valuable to intermediaries that don’t care or want to know about the content being exchanged.

Link headers vs. Custom headers

I really like the logical concept of Link headers.  The syntax of the header is also solid and fine.  The problem I have with it though is that it is non-trivial to parse.    Please, please, correct me if I’m wrong, but parsing a Link header, according to the current version of the spec, isn’t as easy as doing a few string.splits or simple regular expressions.  This is because ‘;=,’ characters can be embedded within quotes.  The ‘;’ can also be embedded within links and media types.  Not only this, but to get at a specific link I have to parse all the links defined within the header and create a map, before I can define a specific link.

Granted, its not hard to write a parser for this.  It is a micro format.  The problem is that HTTP libraries generally do not have native support for this.  Not a very big deal, but IMO, one of the big selling point of REST is its low footprint and the ability to leverage existing libraries to make HTTP invocations.  I came across this problem when writing a Javascript client.

This made me think about redefining the problem.  Instead, isn’t a Custom HTTP header easier to interact with from an API point-of-view?  Do clients and servers really need the media type information (or really any other metadata) about the link?  Could we instead have a simple custom header?

HTTP/1.1 200, OK
Front-link: http/.../front.jpg
Back-link: http://.../back.jpg
Content-Type: image/jpeg

...

Then its just a matter of hash lookup using existing HTTP library facilities.

The downside of course to all of this is that you lose all the self-description aspects that are provided by Link headers.  Specifically the media type (type attribute) as well as IETF registered links vs. custom link relationships referenced via a URL.  IMO, this self-description metadata within Link headers also helps to mitigate against namespace clashes where different domains might define the same header names.

Header Templates?

What if the Link header spec defined a template for header names?  like Link-{rel}, Link-{rel}-Type, Link-{rel}-Title, etc…  Link-{rel}-{attribute}  So, my response might look like this instead:

Link-Front: http:/.../frong.jpg
Link-Front-Type: image/jpeg
Link-Back: http:/.../back.jpeg
Link-Back-Type: image/jpeg

To find links published by a resource is just a matter of iterating through and doing a “startsWith(‘Link’)” on the header.