Inconsistent meaning of field “href”

[tripu]

In the API, href sometimes contains a HATEOAS reference (another URL for the API where more data can be discovered), and sometimes it contains a regular URL intended for humans (eg, the URL of a page or image under w3.org).

For example, look at all values returned inside href properties here:
https://api-test.w3.org/groups/68239

This may not seem like a big deal, but when trying to use the API programmatically (without hard-coding field names etc), this is an issue. Apiary doesn't know if a href is a hyperlink it should simply return to the user, or a pointer to fetch more information from the API. (Yes, it could check the beginning of the URL, but I think that is a weak patch for the issue.)

I suggest we always use href only for API URLs, and url only for URLs of resources outside the API.

[vivienlacourba]

For link objects the href property is mandatory see the relevant HAL spec section on Link obects.

Maybe we could add a "type" property on link objects with the value application/hal+json when we are linking to an API resource, I am not sure if this is feasible in our current code and would also make the API results a bit more verbose.

[tripu]

For the record, @vivienlacourba pointed me to https://tools.ietf.org/html/draft-kelly-json-hal-07 and https://groups.google.com/forum/#!searchin/hal-discuss/link/hal-discuss/H1V0cfMttcI/JyUgTqT79PoJ.

That last thread seems to indicate that there's no obvious way to tell apart links that stay within the API from links to anything else in the world.

@vivienlacourba: can we at least have that type property you suggested? That sounds very good to me, and it would be enough for clients of the API to know whether they should follow an href to fetch more data, or treat that URL in some other way…

[tripu]

FWIW, my two API clients don't need this any more: I'm mostly hard-coding fields and properties (for reasons outlined in #73 (comment)), so my clients know how to tell apart subsequent API calls from other URIs. In the worst case, I can look at the origin of any link and see if it matches the origin I know for the API (it's a bit ugly, but this issue isn't progressing, and the ideal of full auto-discoverability isn't feasible anyway).