you are here

What the Heck are CURIEs?!

Short Answer: CURIEs provide a shortcut or template for linking to API documentation within a HAL based API response.

Long Answer: CURIEs were implemented into HAL to let users identify/ group links while providing a URL template to shorten the linking process and reduce data transfer.  This was done to make the API more discoverable, although this concept is slightly flawed as it makes the API discoverable to HUMANS, unless the documentation link is specifically written for machine to machine interpretation (in which case it’s genius).

To get started, in your HAL specification you would add the curies section like so:

Then you would add your links but use the CURIE name as a prefix, so in the case of the doc CURIE you would start the name of your link off with doc: as shown below:

Now when the _links section is read by a HAL client, the client knows that the documentation for the latest-posts link can be found at http://haltalk.herokuapp.com/docs/latest-posts even though the href link for that resource is presumably http://api.domain.ext/posts/latest. This is done by grabbing the referenced template and replacing the {rel} placeholder with the link identifier/ name (latest-posts).

One problem with CURIEs, however, is that the link name is tightly coupled to the documentation link, making them extremely inflexible.  This means that you have to be careful not to change your documentation URIs as you really should not be changing your link names as clients may rely on them (looking specifically for that key).  It is a major constraint of CURIEs, but I guess having strict URIs is better than not.  Although I would recommend something along the lines of CPHL or adding your own reference to documentation in order to avoid being so tightly coupled.

You can read more about CURIEs in the HAL Specification draft.

Share this Page:
Facebook Twitter Linkedin Reddit Tumblr Email

2 Responses to “What the Heck are CURIEs?!”

  • Sammy says:

    Thanks for clarifying curie’s. But why do you write that they are inflexible and that one needs to be careful not to change the documentation URIs?
    If the Api is driven by hypermedia then the URIs should not matter. That should mean that the documentation is looked up (from the curie) and basically may change whenever.
    Or did I miss something?

    • mike says:

      The problem I have with curies is that they are tightly coupled to the property name – such as ea:find, ea:order, or ea:admin. The problem here is that while the URI can change, the property itself cannot (as the client needs to be able to store the identifier). This means your documentation URI cannot change (outside of the base URI) without having to change the property name.

      Ideally you’d have redirects in this case, but it is still an approach that requires tight coupling. As such I’m much more of a fan of moving away from curies and having a templated documentation link provided within the response, such as “docHref.”


Leave a Reply

Your email address will not be published. Required fields are marked *