Jake Lucas Jake Lucas - 22 days ago 8
reST (reStructuredText) Question

What should a link extension relation type URI point to in a RESTful API?

I've been designing an API recently that needs to be RESTful, and have managed to define a system that uses exclusively HTTP headers and query string parameters to define meta data so that the body of responses is free to just be actual resource data only.

However I'm now thinking about links for HATEOAS, and due to wanting to keep everything in HTTP headers or query string parameters I've decided on using the HTTP

Link
header field.

This has brought up a question about the
rel
attribute that I'm having trouble finding a direct answer for.

My idea is that for collections of resources one of the
Link
s that will be sent in a response will be something like:
Link: <https://api.domain.com/things/{id}>; rel="..."


This would allow a client to use simple string expansion, as defined in RFC6570, to create a correct resource URI for each resource in a collection without me having to embed meta data into each resource and without the client needing to know anything other than the URI template and the resource ID.

However, I'm not sure what the
rel
should be here, or what it should point to.

In RFC5988, it says that an extension relation type must be a URI and:


Although the URI can point to a
resource that contains a definition of the semantics of the relation
type, clients SHOULD NOT automatically access that resource to avoid
overburdening its server.


My question is, what should the definition look like in a RESTful API?

By the looks of it I could just make the
rel
something like
https://api.domain.com/media/thing
, or something like that.

But then what should the actual definition content be?

It looks like it could technically be anything, for example a plain text document with a short explanation.

Is there any RESTful standard for these kinds of
rel
attributes and what they should point to?

Any help is appreciated.

Answer

Looking at Richardson's Maturity Model level 3, rel seems to be representing the name of the published link/relationship. In your case that might translate to curie:thing-by-id (provided you're using curies as suggested in the proposed HAL draft), for example. The idea is that the client could search a link by its name (rel), without peering into the actual url.

Comments