Search code examples
jsonrestjax-rshateoas

Hateoas links in Header or in Entity


I've seen two primary ways to add JSON REST Hateoas and I'm not sure which is more standard or the pros and cons of each approach.

The typical approach I see (Atom Links) is that the returned entity is appended to with a field named either links or _links. This field is an array of rel=<rel> and href=<href> pairs.

But I've also seen (Link Headers) links put into the header value named "Link". The Link is a collection with the format <hef>; rel=<rel>.

Also, I noticed that in JAX-RS there doesn't seem to add Atom Links with fully qualified hrefs, only paths. By fully qualified I mean scheme and authority included. Is it looked on as bad practice to have a complete URI for the href when using Atom Links for HATEOAS?


Solution

  • All the HATEOAS formats i know use the link relationship RFC https://www.rfc-editor.org/rfc/rfc5988 to abstractly define a link relationship. This rfc describes the Link header which is a fine way for conveying link relationships. Other formats serialize/present links in different ways. _links is probably most associated with the HAL+JSON format, while links is used by Siren and COLLECTION+JSON (which also allows for link headers).

    It's all a matter of preference. Many times it comes down to asking if you think of link relationships as metadata of the resource or actually part of the resource. Sometimes it's both. HTML primarily treats them as part of the relationship and has been wildly successful with that. Having them in the response body of the resource makes it very easy to see them in a browser, headers are a little trickier to see.

    Regarding URLs being absolute, scheme relative, root relative, path relative. That again is all preference. Something i like to keep in mind is that a resource is not always retrieved from a request, thus relative paths often can be useless. For example, storing a resource in a cache or on disk. Absolute or scheme relative URLs are much more portable across systems and I personally prefer them over root or path relative URLs in most cases. There are interesting scenarios where you may actually want URLs to be relative so they target different destinations depending on the executing environment. There was an interesting discussion on this recently in the HAL forum: https://groups.google.com/forum/#!topic/hal-discuss/_rwYvjLOT7Q