5

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.

2
  • Thanks! I know how to accept an answer, but usually wait a couple days. Thanks for a prompt response, though! Sep 19, 2012 at 2:34
  • There are tools out there that do this sort of thing. I experimented with swagger-ui a few months back, it may be worth a look for you as well. github.com/wordnik/swagger-ui
    – Tim
    Oct 22, 2013 at 3:59

1 Answer 1

2

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.