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: