resthttp-headersapi-designhateoascurie

Is there a standard way to define CURIEs in HTTP header fields?


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.


Solution

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