Search code examples
jsonapihateoashal-jsoncurie

Can anyone provide a good explanation of CURIEs and how to use them?

I've seen CURIEs described in the HAL specification. At first glance, it looks like a way to provide templating for URIs. However, I also see it prominently mentioned that it can be used to access documentation on a rel. Which one is it? Is it simply a templating mechanism? Does anyone have an example for a good use case?

Also, would the following be a legal use of a CURIE? Or should it only be used to provide documentation on a rel?

    { 
        "id": 1,
        "name": "Social Media Bundle",
        "_links": {
            "self": {
                "href": "http://my.api.com/bundles/1"
            },
            "curies": {
                "name": "bundle",
                "href": "http://my.api.com/bundles/1{rel}"
                "templated": true
            },
            "bundle:channels": {
                "href": "/channels"
            }
        }
    }

Here bundle:channels would be expanded to http://my.api.com/bundles/1/channels.

Solution

  • According to page 7 of the HAL spec, curies are a suggested means by which to link documentation of a given resource:

    Custom link relation types (Extension Relation Types in [RFC5988])
    SHOULD be URIs that when dereferenced in a web browser provide
    relevant documentation, in the form of an HTML page, about the
    meaning and/or behaviour of the target Resource. This will improve
    the discoverability of the API.

    The CURIE Syntax [W3C.NOTE-curie-20101216] MAY be used for brevity for these URIs. CURIEs are established within a HAL document via a
    set of Link Objects with the relation type "curies" on the root
    Resource Object. These links contain a URI Template with the token
    'rel', and are named via the "name" property.

    {
  "_links": {
    "self": { "href": "/orders" },
    "curies": [{
      "name": "acme",
      "href": "http://docs.acme.com/relations/{rel}",
      "templated": true
    }],
    "acme:widgets": { "href": "/widgets" }
  }
}

    The above demonstrates the relation "http://docs.acme.com/relations/ widgets" being abbreviated to "acme:widgets" via CURIE syntax.

    The CURIE spec itself, has nothing specifically to do with documenting resources and is designed to enable compact URIs.

    To answer your question, my interpretation of the specs would suggest that you have legitimately used the curie syntax but not in the context of HAL.