Link headers vs link elements for RESTful JSON

Question

When building a RESTful / hypermedia API with JSON resources, it seems I have two options for specifying the hypermedia relationships between resources.

1. Embed the links in the body of the JSON document. The problem here is that there isn't a standardized syntax for specifying hyperlinks, although I see a number of good efforts: (HAL, Collection+JSON, JSON-LD, JSON Schema to name a few).

2. Use HTTP Link headers. This is a standardized, so this seems to have an advantage over embedded links. Clients just understand how to make sense of the standard header and voila, hypermedia goodness is achieved.

So, specifically in the context of handling JSON resources, which is the way to go and why?

Answer 1

If you want your links to be processed by HTTP intermediaries then you should definitely use Link Headers. One example of this is Linked Cache Invalidation :

http://tools.ietf.org/html/draft-nottingham-linked-cache-inv-01

If you just want to expose links to your clients you're better off putting them in the entity in order to take advantage of links within nested elements :

{
    'item': [
        { 'name': 'fork',  'href': 'http://example.com/item/1' },
        { 'name': 'spoon', 'href': 'http://example.com/item/2' },
        { 'name': 'spork', 'href': 'http://example.com/item/3' }
    ],
    'href': 'http://example.com/items'
}

Answer 2

It seems to me using both alternatives (Link headers and hypermedia links in the response body following a standard format such as HAL) allows your solution to reap the benefits of both approaches. Of course that sounds like a good idea if your REST development framework supports automatic creation of the links in both places.

Answer 3

Go with a hypermedia JSON format. While Link Headers are standard, they're poorly adopted. They're really more valid for media formats that are not hypermedia. But since you have a choice and can choose a hypermedia format (unlike, say, PNG vs JPG), you should simply choose one and move forward.

All of the JSON standard are bubbling about until one or another becomes a "de facto" standard. The more they're used, the more "de facto" they get.

Seems to me that HAL is on a solid Standards track, and I would pick that.

But either way, go with a hypermedia format because you can.

Answer 4

• Link headers can be considered by intermediaries
• Link headers are compressed by SPDY
• Link headers are standard

They can even contain some JSON if needed! http://tools.ietf.org/html/draft-nottingham-link-hint-00

This approach allows delivery at the same time in all responses:

• Link Headers containing hypermedia information
• a payload devoted to resource representation

Of course the resource representation may contain links encoded in various forms, but the use of Link headers can provide the most important part of the dynamic structure of your site.

What makes this solution definitively appealing is IMHO the "accept-post" hint.

Answer 5

You can't compress headers. If you have a lot of links. That might make a difference.

Providing context for a link. Link headers have the anchor attribute, but there is no standardized fragment path syntax so YMMV.

Off the top of my head I can't think of any other pros/cons.