Incorrect interpretation of the HAL RFC wrt curies

[joshco]

Im having trouble with curies and what appears to be a difference in behavior in hyperclient vs hal-browser. Hyperclient is templating urls when not expected.
My server returns:

"curies": [
      {
        "name": "osdi",
        "href": "http://opensupporter.github.io/osdi-docs/{rel}",
        "templated": true
      }
    ],
    "osdi:tags": {
      "href": "http://demo.osdi.io/api/v1/tags",
      "title": "The collection of tags in the system"
    },

In the hal browser, the curie is just used for documentation links and it does not reformat the link URL, which is already absolute.
But in hyperclient, it is reformatting the url for the link itself as:

http://opensupporter.github.io/osdi-docs/http://demo.osdi.io/api/v1/tags

How do I reconcile this? Can I disable curie reformatting in hyperclient?

Reference: #64

[joshco]

pull request fix created

[dblock]

This is clearly a bug, thanks for suggesting a fix.

[dblock]

About this issue here, why are you using a curie in the osdi:tags example? Should this just be tags, in which case the issue is moot?

[joshco]

perhaps we should separate the two issues and I'll move the query params out of this issue.
I think the issue of avoiding expansion when the href is already absolute should stay open.

[joshco]

I think there is a misinterpretation of how curies are supposed to be used in HAL. Curies are meant to shorten the key names in a _links hash, not the actual href associated with a link in the _links hash, as well as provide a link to the human readable documentation for said link.

https://tools.ietf.org/html/draft-kelly-json-hal-07#section-8.2

8.2. Link relations

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.

So actually, hyperclient shouldn't be doing any template expansion when dealing with curie syntax at all when navigating to a curied link.

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.

When a curie is present, the href template inside the curie is how to find the documentation, not the resources. In the example above (from the spec), the resource is widgets, but the curie href refers to the documentation for wigets.

[joshco]

Created pull request for that
#100

[dblock]

Fixed in #101.

[dblock]

Closed via #101.