Every response should contain hyperlinks to other resources, where the structure/metadata around it indicates what's on the other end. It should still be self-describing even if the URL is completely opaque -- "nice URLs" do not make you RESTful.
You should never need an "endpoint" or any documentation at all, whether machine or human-readable. I should be able to explore your whole API just using HTTP. Ideally you'd use the exact same URLs for your API and browser-human interfaces, using the Accept: header to get different representations of the response.
Almost everybody fucks this up, and just uses 'meaningful' URLs that you're expected to build yourself, and lots of sassy human documentation to tell you what the constants are.
– Hacker News | True REST abhors the idea of separate "standardized, machine-readable documentat....
Total rubbish, of course. The only actual 'proper' REST interface anyone I talk to can come up with is AtomPub and that's awful. Me, I like XMLRPC. Forget the 'XML' part - it's RPC. RPC that is very very simple and works and every endpoint works the same. I've lost count of the number of times I've had to write yet another bloody 'encode form variables and parse response as JSON' clients for supposedly 'REST' APIs.