1

Recently, I've designing a RESTful API, and I want to use the Link header field to implement HATEOAS.

This is all fine and works without any real problem, but I want to make it easier for the clients of the API.

The Link header for example might look like this:

Link: <https://api.domain.com/orders/{id}>; rel="https://docs.domain.com/order"

In this case the client would have to find the link by searching for the https://docs.domain.com/order value in the rel attribute.

This works, but since the URI for the docs could change it's fragile, and because of the length it makes it a bit impractical as a key to search for.

So I want to try and use a CURIE to make it something like this instead:

Link: <https://api.domain.com/orders/{id}>; rel="[rc:order]"

That way the problem of a URI changing is mitigated for the most part, and it's much more compact allowing for easier search by the client.

My problem is, that since I'm using a Link header field to implement HATEOAS I feel it would be most consistent to also include the CURIE as an HTTP header field, rather than introducing meta data in the response body.

Since the entire API uses standard HTTP header fields and status codes for all of it's meta data (pagination, versioning etc), I would rather not introduce meta data into the response body just to define a CURIE.

But if I use HTTP header fields, which field should I use for a CURIE?

Is there even a standard way to do this with HTTP header fields?

If not, should I just use a custom header field, like X-Curie: <https://docs.domain.com>; name="rc", and just document it somewhere for clients?

I've looked around and most resources are either in reference to XML or the HAL standard, so any information on this in relation to HTTP header fields would be appreciated.

Jakob
  • 3,570
  • 3
  • 36
  • 49
Lucas
  • 10,476
  • 7
  • 39
  • 40

3 Answers3

0

No, you can't do that. The link relation is a string - nothing more.

The question that you should ask yourself is why you are using an unstable link relation name in the first place...

Julian Reschke
  • 40,156
  • 8
  • 95
  • 98
  • Because that's what the web linking RFC requires. It states: "Applications that don't wish to register a relation type can use an extension relation type, which is a URI [RFC3986] that uniquely identifies the relation type" then it says: "When extension relation types are compared, they MUST be compared as strings (after converting to URIs if serialised in a different format, such as a Curie [W3C.CR-curie-20090116])". So a URI is required and a CURIE is allowed, I just wondered if there was a standard way to define a CURIE. It doesn't mean the URI is definitely unstable, but a CURIE is better. – Lucas Nov 13 '16 at 23:27
  • At least that's my understanding of the RFC anyway. Of course I don't _have_ to use a CURIE, I just thought if there was a standard way to define a CURIE in HTTP header fields that would make things a bit nicer for clients. – Lucas Nov 13 '16 at 23:29
  • @JakeLucas - you are misinterpreting that part; it's about link relations that appear in other formats than HTTP header fields. – Julian Reschke Nov 14 '16 at 03:33
  • I've been re-reading the RFC but have trouble following certain parts of it. So I'm guessing that what you are saying is that something like a CURIE is not possible in an HTTP header field because it says further down: "Note that extension relation types are REQUIRED to be absolute URIs in Link headers"? I didn't notice that part, so if my understanding is now correct it means I have to use an absolute URI for the `rel` because it's a `Link` header, and that's all there is to it. Is that correct? – Lucas Nov 14 '16 at 04:44
  • Yes - either absolute URIs, or register them as a general purpose link relation. – Julian Reschke Nov 14 '16 at 05:36
  • Thanks for the confirmation :) – Lucas Nov 14 '16 at 05:40
0

Even if you don't use the Link header, CURIE's would not solve the problem you present. Because the CURIE's standard state that a shortened URI must be "unwrapped" before any comparison is performed. This would also apply to comparison agains the link relation in question.

A more pragmatic approach would be to coin your own URI like foo:order. Then you can use some custom url shortening method of resolving the documentation url for the relation in question. This method is used by hypermedia formats like HAL+JSON (the HAL formats use of curies is actually misleading, it should only be used as a method for resolving URL's to documentation).

Fredrik Sjöblom
  • 1
  • 3
0

CURIEs in HTTP Link header's rel properties would not get expanded, because all rel properties are equated with simple string matches, none are treated as URIs.

My main concern would be the phrase "since the URI for the docs could change it's fragile" — then choose a URI which won't change. Even if you use a URL that redirects to some location deep in the docs, the URI you choose for the link relation needs to be permanent if you want client devs to be able to resolve it.

Nicholas Shanks
  • 10,623
  • 4
  • 56
  • 80