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

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.