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?

Answer 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.

Answer 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.