openstack team mailing list archive

[Joseph Heck <heckj@xxxxxx>]

Jorge - 

It's way back the beginning of this thread - A consolidated single website with API docs as HTML pages that is easy for developers to consume. I'm looking forward to seeing the WADL parser, already on that thread with David Cramer directly. I can wait until he's got it in github, which he said would likely be next week.

The docs generated on doc.openstack.org are all in docbook format - neat, but not what I'm after. As I mentioned some 40 msgs back (now quite lost, I'm sure), what I'm looking to create is something like these sites provide:

	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/

That we can generate (ideally dynamically, but I'm not wedded to that) from the API's of all of Nova, Glance, Keystone and Quantum - both what we've labelled as core and extensions.

My goal isn't to make, parse, or manually read WADL's - it's to make this set of web pages. If WADL helps me get there expediently, I'm all over it.

-joe

On Oct 27, 2011, at 11:03 AM, Jorge Williams wrote:
> As I stated in previous emails, we are pulling data from the WADL to grab human-consumable REST API docs that live at docs.openstack.org today.  We can certainly expand that capability to create a unified API documentation set rather than individual guides.  A lot of the hard work for parsing is already done, and we'll be releasing a WADL normalizer that puts the WADL in an easer to process form.
> 
> Joe, I'd love to hear more about what you're trying to accomplish.  Maybe we can help you leverage the tools we have to accomplish them.
> 
> -jOrGe W.
> 
> 
> On Oct 27, 2011, at 10:51 AM, Joseph Heck wrote:
> 
>> Yeah, that's what I've been poking at and the original start of this rather lengthy thread. Unfortunately, WADL, while it appears complete, is rather obnoxious for pulling out data. Or more accurately, I haven't fully understood the WADL specification in order to write a WADL parser to allow me to do just that. I'm poking at it now, but my original goal wasn't to write an XML parser but to just create a unified API documentation set on a web site to make it easier to consume OpenStack services.
>> 
>> -joe
>> 
>> On Oct 27, 2011, at 8:04 AM, Lorin Hochstein wrote:
>>> It would be great if we could do some kind of transform of the IDL to generate (some of) the human-consumable REST API documentation that lives at docs.openstack.org. That would simplify the task of keeping those docs up to date.
>>> 
>>> Lorin
>>> --
>>> Lorin Hochstein, Computer Scientist
>>> USC Information Sciences Institute
>>> 703.812.3710
>>> http://www.east.isi.edu/~lorin
>>> 
>>> 
>>> On Oct 27, 2011, at 9:54 AM, Sandy Walsh wrote:
>>>> Sounds awesome!
>>>> 
>>>> I've done an application like this in the past where an entire web UI was data driven using a custom IDL. It had to have presentation hints associated with it (acceptable values, display widget, etc). Not something WADL supports inherently I'm sure. But, I know from experience this can work.
>>>> 
>>>> I don't really care what the IDL is, so long as we don't have to write a parser for it in 10 different languages ... which is why XML/JSON hold such appeal (although JSON in C keeps me awake at night).
>>>> 
>>>> -S
>>>> 
>>>> ________________________________________
>>>> From: Mark Nottingham [mnot@xxxxxxxx]
>>>> Sent: Thursday, October 27, 2011 10:38 AM
>>>> To: Sandy Walsh
>>>> Cc: Mellquist, Peter; Joseph Heck; openstack@xxxxxxxxxxxxxxxxxxx
>>>> Subject: Re: [Openstack] +1,  All services should have WADLs
>>>> 
>>>> I'm totally on board with having the interface being machine-consumable at runtime -- see the previous discussion on versioning and extensibility -- but WADL isn't really designed for this. I'm sketching up something more appropriate, and will be able to talk about it soon (hopefully).
>>>> 
>>>> 
>>>> _______________________________________________
>>>> Mailing list: https://launchpad.net/~openstack
>>>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>>>> Unsubscribe : https://launchpad.net/~openstack
>>>> More help   : https://help.launchpad.net/ListHelp
>>> 
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>> 
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>