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 t

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'
}