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

Leave a Reply

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