Is there a standard for machine-readable descriptions of RESTful services?

Question

I've interacted with a few RESTful APIs that provided excellent documentation for humans and descriptive URIs, but none of them seem to return machine-readable descriptions of themselves.

It's not too tough to write methods of my own that assemble the right paths, and many language-specific API libraries are already just wrappers around RESTful requests. But the next level of abstraction seems really useful: a library that could read in an API's own machine readable documentation and generate the wrappers automatically, perhaps with a call to some standard URI like base_url + '/documentation'

Are there any standards for machine-readable API documentation? Am I doing REST wrong? I am a relatively new programmer, but this seems like a good idea.

Answer 1

Yes, there are multiple ways that you may use.

One of them is to generate your client code, tests and documentation using a set of tools supporting WADL. Some examples can be found in this blog post.

You may also find it better to use WADL, rather than WSDL 2.0 because it is less verbose and way simpler (IMHO). In fact, by using WADL you describe exactly what the user sees on the documentation page, just using WADL XML syntax. And it is also one of thereasons why it's so easy to write XSLT-based documentation generators for WADL.