Hateoas links in Header or in Entity
Asked Answered
A

2

6

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?

Accredit answered 19/11, 2014 at 17:19 Comment(0)
U
7

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

Undulate answered 25/11, 2014 at 18:36 Comment(1)
I'd love it if you removed your "It's all a matter of preference" after reading my experience with links in headersOstium
O
3

Adding another answer because HATEOAS links in headers have bitten us. If we had the option to do it again we would surely use links in the payload instead of the headers

The main reasons are:

  • When querying a collection, getting links for each of the records requires some special way to allow you to know which of the records a link is for.
    • <cry>We misused the title attribute to be a record ID </cry>
  • You can easily get a 431 Request Header Fields Too Large error if you have too many links.
    • <scream>Our collections don't send the all the links because of that limitation, which means we have to fetch every instance separately to have access to all the actions.<\scream>
Ostium answered 5/10, 2022 at 14:20 Comment(1)
Hydra uses RDF vocabs to describe links. They bind links to operations in these vocabs not to link relations. So link relations is not the only approach currently though hydra supports link relations too. hydra-cg.com/spec/latest/coreStickney

© 2022 - 2024 — McMap. All rights reserved.