openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Ah yes,

API reference pages that span all the projects.  That's totally doable, I know we had plans for doing such a thing, but not sure where those plans are.  We were planing on using WADL for that.  Maybe we should get together with some of the doc folks Anne, David to come up with a strategy. How about we discuss at the next Doc Team Meeting  http://wiki.openstack.org/Meetings/DocTeamMeeting

-jOrGe W.


On Oct 27, 2011, at 1:20 PM, Joseph Heck wrote:

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<http://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<http://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<http://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<mailto:mnot@xxxxxxxx>]
Sent: Thursday, October 27, 2011 10:38 AM
To: Sandy Walsh
Cc: Mellquist, Peter; Joseph Heck; openstack@xxxxxxxxxxxxxxxxxxx<mailto: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<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp