[AffableSpatula]

Your applicaiton's link relations should be URLs. This means that you can expose each bit of documentation for each rel at their URL. So every time you see a link in a hal+json document, you can follow the _rel's_ URL, and fetch the documentation for it.. that turns out to make the API very easily discoverable, and gives you a way to model/manage your API's documentation in a consistent way.

You can actually see what that looks like in practice here (click one of the book icons on one of the links on the left):

http://haltalk.herokuapp.com

[justsee]

That's a really nice example of it in action. Thanks for putting in the effort to explore standardising links like this.

I really like the human discoverability feature that you've demoed, and gameche's point about being able to include resources outside the scope of an API is certainly interesting, but I'm still confused about the primary feature you championed, which is the ability to easily change URL structures.

You championed that as a core feature in your post: "make it painless to change your application’s URL structures further down the line".

dhh's retort knocked that feature on it's head, didn't it? Once you settle on coding against a particular section of an API, you're relying on a URL. Your feature works with an API depth of 1, but beyond that what is the proposed approach? To traverse the API from "/" every time, making multiple calls until you discover the right link reference which contains the latest URL for that resource?

[mjs]

Do you mean like http://haltalk.herokuapp.com/rels/signup? But every site will have different requirements or mandatory fields on signup, so there's still no "discoverable" way to sign up to Amazon and eBay and Google without a human looking at http://amazon.com/rels/signup and http://ebay.com/rels/signup, etc., in which case you're back to still needing to read the documentation.

I guess it's a slight improvement to know exactly where the documentation for a particular link relation will live instead of having to search for it, but it doesn't seem to solve an especially difficult problem.

[AffableSpatula]

it is an example of a discoverable API with discoverable documentation though, which is what you were asking for I think.. maybe not?

[mjs]

Ah, maybe I misunderstand what you're trying to do. I thought Hal was trying to make it possible to write clients that can buy from Amazon or eBay without knowing anything about the specifics of either. But actually what it's attempting is a sort of machine-assisted documentation system? (Since you still need a human to read the docs to find out how to signup, place orders, and so on.) I can see how that might work, but it doesn't seem like an important problem to solve.

[AffableSpatula]

That is one of the benefits that relates to documentation, which is the part of your comment I was responding too.

The larger goal of hal+json is to establish some conventions for linking that allow the development of generic tools for doing hypermedia. Not to create magical machine clients that can interact with any random API you point them at. Nobody made that argument so I don't know why DHH addressed it in his post. I'm guessing he ran out of things to be an angry-pragmatist about.

[mjs]

Well ... the spec does say "HAL is a bit like HTML for machines, in that it is generic and designed to drive many different types of application." To me (and perhaps DHH), that suggests that it's designed to be used to create clever clients. Perhaps you can clarify this point in a future edition of the draft?

http://stateless.co/hal_specification.html

[AffableSpatula]

I have no idea why you would conclude that from that sentence. HTML allows browsers, the same way that HAL allows generic libraries. I'm struggling to understand why this is controversial, there are already 16+ examples of generic HAL libraries across a bunch of different languages.