gistfile1.md

How to embed HATEOAS/Link inside JSON

HTTP Headers

For HTTP headers it's quite straightforward: draft-nottingham-http-link-header defines this.

Link: <http://example.com/>; rel="previous"; titile="Previous chapter"

Perl's LWP library automatically parses this headers, and in Ruby there's link_header gem.

Implemented in GitHub API v3.

RESTful JSON response

There's a couple of ways to embed links inside a JSON data structure. Here's the list I can come up with:

rel as a key, url as a value

{
  "id": 1234,
  "name": "Bob",
  "links": {
    "self": "/people/1234"
  }
}

Pros:

• Simple. Easy to parse and access in client libraries

Cons:

• Can't include attributes other than href. What if I want to include title and type for example?
• Can't have multiple links with the same rel, although i think it is a bad practice to have multiple links with the same relationship anyway.

Facebook Graph API implements this format under connections if you request the API with ?metadata=1.

rel as a key, url as a hash

{
  "id": 1234,
  "name": "Bob",
  "links": {
    "self": { "href": "/people/1234" },
  }
}

Pros:

• Easy to parse, yet extensible and can include other attributes

Cons:

• Can't have multiple links with the same rel. Same as above.

GitHub API v3 implementes this format in some of the data types.

links as an array

{
  "id": 1234,
  "name": Bob,
  "links": [
    { "rel": "self", "href": "/people/1234" }
  ]
}

Pros:

• Extensible and straightforward.

Cons:

• A little bit annoying to parse, although it could be still one-line grep or select in most languages, and you can write a wrapper anyway.

Ruby gem roar implements this format.