Contextual links in hypermedia content

Posted on 23. Feb, 2010 by Guilherme Silveira in restful

Because resource meta data is sent through http headers on the human web we usually try to think it should be done in the same way in the RESTful web.

With the overall public acceptance of the Link header, I started to worry that some of the meta data that was important to dynamic resources would not be so easily understood by clients.

The human web nowadays

If you take a look in the human web, links appear within representations.

This way service providers are capable of adding links in their own context and the representation is therefore called “hypermedia“.

Consuming clients are aware that those links are related to a specific part of a resource: links are not globally related to the entire resource but most of the time, they relate to parts of its representation.

Open your favorite content provider and enter a random article. Note that links from that resource and found within the resource and provides a much better understading for you of what will happen if you open links related to each part of the resource being read.

Headers

Meanwhile the Link header suggests that this metadata, that makes our resource hypermedia, is inserted in an area that relates to the entire resource, not part of it, thus making your resource non-hypermedia again.

Note that by providing links to related resources and state changes through headers might still achieve HATEOAS, but in a more limited way.

If you take wikipedia as an example, can you imagine a series of links being displayed in a different section of your browser, and the entire text in a separate part?

The answer is, of course, that it makes no sense, and the browser would need to be more intelligent and find a way to connect both the provided links and the current content so the final client (you, in the human web) actually can click on some content.

But now we are back to were we started… the client sees the same content that was provided earlier (with pure xhtml), but two extra steps were inserted in the way: decoupling the links from the content on the server side and contextualizing them back in in the intelligent client.

Seems like a lot of extra work for something that we already have.

Anchors

The link header proposal supports contextual links through the use of custom anchors, thus a resource server that understand anchors might provide in the header fields only those that relate to part of the request resource but this requires a two step request retrieval.

(small note: the first request returned the list of frameworks, amongst other data. the second one retrieved the links for those frameworks)

Summing up

Restfulie already supports the Link header, but we do not recommend it over well known representations that accept contextualized relations. The richer the resource, the more important will be those relations.

Mark’s proposal and link headers are important and will become a standard solution for media types that are not hypermedia but should not be used for those who already provide these contextualized relations.

Tags: hateoas, header, hypermedia, link, restfulie