Monday, October 4, 2010

Evolving HAL

I've decided to revise and update HAL after some feedback and pondering.

HAL is a hypertext format for m2m interaction. It provides the following hypermedia factors:

  • Embedded Links (LE)
  • Out-bound navigational links (LO)
  • Templated Queries (LT)
  • Link relations(CL)

HAL specifies two elements:
  • link
  • resource

Both elements share the following attributes:

  • @rel
  • @href
  • @name

The link and resource elements differ in the following ways:

Link elements..
  • The link element is intended for representing out-bound links and should be written with solo/self-closing tags.
  • @href value of a link element may contain a URI template to express a templated query link.

Resource elements..
  • The resource element is intended for representing the embedded state of other resources and should be written with open and close tags, with the embedded representation contained within.
  • The root element must always be a resource with an @rel of self and an appropriate @href value.

Other rules:
  • @name must be unique between all HAL elements (link + resource) with the same @rel value in a document, but should not be considered unique within the entire document. This means a link element cannot be referred to by @name alone (thanks to Darrel for this)
  • The subject of an @rel is always directed at the closest parent resource element.
    e.g. A link that appears within an embedded resource relates to the embedded resource, and not the root resource.

Here is an example:



And here's how that might look in json:

4 comments:

  1. One comment about uri-templates.

    Maybe it should be stated somewhere that this is a uri-template, so you don't have to introspect the href attribute to figure that out.

    I suggest a new type for that, either as an element like "link-template", or as an attribute href-template="" which MUST be present, which makes the href attribute illegal.

    ReplyDelete
  2. Hi Erlend,

    That's a fair point - when I discussed hal with everyone on IRC this was raised as an issue.

    My personal preference, if I had to, would be to add a 'link-template' element.

    However, I've chosen not to add that for the time being because, afaict, uri-template applicability for a given link can be indicated by the rel (e.g. rel='search'). And, at the moment, I can't envisage any cases where that approach would not suffice.

    Cheers,
    Mike

    ReplyDelete
  3. hi Mike,

    This is really great stuff. I have a couple of questions since I'm pretty new to HAL.
    1.- Every response of your RESTful service has a root element "resource"?
    2.- How can I tell (or where would that information be) which type of resource it is when using rels like "owner, item, next, prev, self"?
    Cheers!

    ReplyDelete
  4. Hi, Is this part of a bigger project?

    i.e. is there somewhere showing this being used?

    ReplyDelete