Ok, I read your article about HATEOAS and there is one thing that bothers me about the discoverability aspect. The example of the discoverable "newcomment" action that can be done on the resource has no clear semantics; it's just an anonymous link. You claim that you could arbitrarily change the link and a good client would follow along, but how did a client even know that /entry/newcomment was the way to make a new comment in the first place, let alone after you rename it to /somethingelse/whatever?

I assume the examples are just suffering from being oversimplified, because otherwise the whole scheme seems like a huge sham, but I really don't understand how a client is supposed to magically discover the correct endpoint.

HATEOAS isn't the semantic web. You still need a human to translate what exactly "/entry/newcomment" _means_, in the software sense.

But once you have a client that understands one specific vocabulary, if you will, you can use the same client for multiple services which speak that vocabulary.

As an example, think about RSS: RSS is a standard, built on top of XML, which shares certain structures and link relations. A human builds an RSS reader, which understands the RSS format, and then you can use that reader on any RSS-enabled site.

Another example is https://gist.github.com/steveklabnik/2187514 , which understands the 'ALPS microblogging' spec. You can use this microblogging client across any compatible server: http://rstat.us and http://alps-microblog.herokuapp.com/ are two instances.

I'm still not clear on how this is possible: "By the same token, we can change the URI in our <link> tag, and a proper client will just automatically follow along. Brilliant!" If your client has a notion of what exactly "/entry/newcomment" _means_, then how is it going to automatically follow along when the link URI changes?

Before:

{ "/entry/newcomment": "/foo" }

After:

{ "/entry/newcomment": "/bar" }

Because the code says "send a POST request to whatever URL is at the end of the correct rel", it will make a POST to /foo in the first instance, but /bar in the second.

And it also recognizes if such a thing is even present. So, for example: https://gist.github.com/steveklabnik/2187514#file-microblog_...

This implies that _if_ the form with this class is on the page, then we show the "post a new microblog" button. If it's not, then we don't. The client automatically adapts to the server's response.

And where to POST _to_ is here: https://gist.github.com/steveklabnik/2187514#file-microblog_...

Maybe this helps? http://words.steveklabnik.com/i-invented-hypermedia-apis-by-...

Also, I have a mailing list where we discuss this kind of thing: [email protected] . That might be easier than checking HN history, and others can chime in too.

Gotcha, thanks. I knew I must be missing something, and that's it.

No problem. At this point, server-side knowledge is pretty known, but client-side understanding is harder to come by. Those of us on the bleeding edge are working on making it more accessible, but it just requires time and resources our merry little band doesn't always have, you know?

Wow ... Nice to meet you Steve! I'm going to bow out of the discussion since there's an expert here.

Pssssh. Don't do that!