True REST abhors the idea of separate "standardized, machine-readable documentation" like WSDL. The biggest point of REST is that Hypertext Is The Engine Of App

True REST abhors the idea of separate "standardized, machine-readable documentation" like WSDL. The biggest point of REST is that Hypertext Is The Engine Of Application State -- but unfortunately most people focus on bullshit naming conventions that are largely False REST. 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.