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:

	{
	"_links" : {
	"search" : { "href" : "/todo-list/search;{searchterm}" },
	"description" : { "href" : "/todo-list/description" }
	},
	"_embedded" : {
	"owner" : {
	"_links" : {
	"self" : { "href" : "http://range14sux.com/mike"},
	"friend" : { "href": "http://mamund.com/" }
	},
	"name" : "Mike",
	"age" : 36
	},
	"item" : [{
	"title" : "Find Mug",
	"content" : "Find my mug.",
	"_links" : {
	"self" : { "href": "http://home.com/tasks/126" },
	"next" : { "href" : "http://work.com/todos/make-some-tea" }
	}
	},{
	"title" : "Make tea",
	"content" : "For make drunking goodly tea that is green.",
	"_links" : {
	"self": { "href": "http://work.com/todos/make-some-tea" },
	"prev" : { "href" : "http://home.com/tasks/126" }
	}
	}]
	},
	"created_at" : "2010-01-16",
	"updated_at" : "2010-02-21",
	"summary" : "An example list"
	}

view raw halv2.json hosted with ❤ by GitHub