HATEOAS Rel - Any Standards Yet?

Question

I'm just starting to write a client implementation for a WebAPI I'm currently building. The API already employs HATEOAS so I'm writing the client accordingly. I'm using RestSharp as the base for the client.

The Client is passed the api base url at construction time ("https://myapi/start") which it fires a request at and is then passed a set of uris for other available resources - authorisation ( "https://myapi/authorize") and requesting access tokens ("https://myapi/tokens") to authorise it to call into secured resources on the api.

The question is are there any standards drawn up yet for the rel="" requirements in the returned hypermedia?

Solution 1

I believe Hypertext Application Language (HAL) is a draft standard - attempting to standardise these links between hypermedia.

This is a link to the draft JSON specification https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-03

The HAL specification enforces the "href" conforms with the "Target IRI" defined in Web Linking specification (RFC 5988)

There is an XML implementation of HAL using C# here https://github.com/tavis-software

The same GitHub repository above also contains an example .Net implementation of RFC 5988.

Solution 2

The Web Linking spec, RFC5988, as has been pointed out in another answer, defines some different types of link relationships. But it also instructs IANA to create a link relation registry and to allow further link relation registrations. That registry, which is the definitive list of public link relations, is available at iana.org/assignments/link-relations and will be updated as new relationships are registered.

Commonly used relations in HTTP APIs include:

• start (points from every resource back to the API start point)
• item (points from a collection to an item, e.g. from a Twitter user page to a tweet)
• collection (reverse of item)
• previous (these next four are for paginated resources, e.g. collections or multi-page articles)
• next
• first
• last
• create-form (points from a collection to a resource that describes how to create new collection items, e.g. a ‘New Item’ HTML or XForms form)
• edit-form (points from an item to a form for editing that item, e.g. an Edit Tweet button)

If your desired relation is not covered by anything on that list, your relation must be a URI. Further, it is advised to make that URI a dereferencable http URL at a domain under your control so that API clients can look up documentation for the relation, e.g. http://www.example.com/link-relations#tweets. Usually, your API start point will be a list of collections, each with a custom link relation that describes what type of resource each collection contains.

Solution 3

Before talking any further about HATEOAS standards, I want to emphasize that there are three main concepts in an API implementing HATEOAS (nowadays also known as Hypermedia API):

• The HTTP Protocol. You have to respect its constraints when using verbs and return codes. You should also know the role of headers, especially Content-type, and subtilities like idempotency of some verbs. See RFC 2616 for more
• The URI structuration. Which must only give info about targetting a resource, and avoid contextual data. Known bad examples are for example to include language /en/, version /v01/, format /json/ or even verbs /do-something/ in the URI. More about that in RFC 3986 and in REST guidelines
• Contextual data, which can be found in the body, request params, or in the headers

Developers of REST libraries have strong guidelines to follow regarding URIs and HTTP, but lack an universal standard about contextual data and how it mixes with application data in the JSON body of the requests.

This is why the standardisation effort around HATEOAS is mostly about making specifications about the media-type. There are several ones arond there

• JSON HAL (ca 2012), as outlined by Mark Jones is the most known
• Collections + JSON (ca 2013), which did not get much attention
• Verbose (ca 2014) tried to unify every other effort, but is only known by specialists
• Siren (ca 2017) has around 1k stars on github
• JSON:API (ca 2015 but still in progress) is the current reference, with a lot of implementations for its version 1.0, and the support of Steve Klabnik, who authored a lot of content around the subject

Regarding your original question, see HERE for the JSON:API statements about related resource links.

Hope this will help anybody having the same concerns in 2019.

Solution 4

This IETF proposed standard RFC5988 document describes the different types of link relationship and proposed usages. Its focus is on the HTTP Link header specification but it includes a discussion of other link relation types. Like some (most?) RFC's, reading it can leave you more confused than when you started but its worth the effort in the long run. Would it answer what to put between the double quotes in your question? Probably not, but at least you'll get some thoughts to guide your choices.

Solution 5

HAL seems very interesting indeed.

For anyone else looking into this topic or HATEOAS the HAL browser is a must. Check out at the link below:

The Hal Browser on Heroku

View more solutions

Comments

[Jammer]

I try to avoid RFCs where possible ;) Only kidding, although I'm glad I'm not the only one that always comes away with more questions than answers.

[istepaniuk]

the HAL draft link is dead. Any pointers to a live version?

[codesmith]

is broken currently

[Jammer]

Seems back up now.

[Abdurrahman I.]

I haven't seen delete or remove as link relation. Is this because it's not common nor convenient/safe ? Also checked here and apparently no one requested it > github.com/protocol-registries/link-relations/issues

[Nicholas Shanks]

@AbdurrahmanI. Yes, it's bad practice to have a URL that performs a delete/remove on a GET request, so there is no link relation for that so as not to encourage it. Instead there is the link relation "edit-form", which you use on a link to a page that has a <form> element. That form then submits a POST request (usually to itself or the URL of the resource it's editing). You might use a distinct <button name="delete" value="1">, or have a checkbox "[x] Delete this resource", or similar. Think of "edit" as meaning "change or delete".