Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
Thanks! I know how to accept an answer, but usually wait a couple days. Thanks for a prompt response, though! –  ecmendenhall Sep 19 '12 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 '13 at 3:59
add comment

1 Answer

up vote 2 down vote accepted

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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