I will mention that "nobody" is doing this is wrong nowadays. GitHub is one example, and my employer, Balanced is another. Go on, try it:
curl https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo/debits \
-H "Accept-Type: application/vnd.api+json;revision=1.1" \
-u ak-test-1sKqYrBZG6WYpHphDAsM7ZXFEmJlAn1GE: \
-d "appears_on_statement_as=Hacker News" \
-d "amount=5000" \
-d "description=A sample charge to show hypermedia controls"
This request (with test credentials) charges the card stored at https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2...If you GET that card with the same credentials, you'll find a link in the response that points to how to debit.
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.
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.
{ "/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.
"REST is inter-computer communication structured such that the server doesn't maintain any client state so that neither the duration between requests nor the number of clients impacts the resource usage of the server."
It's not quite true, but the architecture has benefits:
1) No need to replicate client sessions in a clustered environment.
2) There's no impact if a client wait hours between requests.
3) Every resource a client uses has a unique location on the network.