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