openstack team mailing list archive

[Joseph Heck <heckj@xxxxxxx>]

I expect this is going to open a nasty can of worms... today we don't have a consistent way of describing the APIs for the various services. I saw Nati's bug (https://launchpad.net/bugs/881621), which implies that all the services should have a WADL somewhere describing the API.

I'm not a huge fan of WADL, but the only other thing I've found is swagger (http://swagger.wordnik.com/spec).  I have been working towards trying to create an comprehensive OpenStack API documentation set that can be published as HTML, not unlike some of these:

	https://dev.twitter.com/docs/api
	http://developer.netflix.com/docs/REST_API_Reference
	http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API
	http://upcoming.yahoo.com/services/api/

To make this sort of web-page documentation effective, I think it's best to drive it from descriptions on each of the projects (if we can). I've checked with some friends who've done similar, and learned that most of the those API doc sets are maintained by hand - not generated from description files.

What do you all think about standardizing on WADL (or swagger) as a description of the API and generating comprehensive web-site-based API documentation from those description files? Does anyone have any other description formats that would work for this as an alternative?

(I admit I don't want to get into XML parsing hell, which is what it appears that WADL might lead too)

-joe