[Openstack] describing APIs for OpenStack consumers

Nati Ueno nati.ueno at gmail.com
Tue Oct 25 23:05:26 UTC 2011


Hi Joe

2011/10/25 Joseph Heck <heckj at mac.com>:
> It sounds like even though most of us hate WADL, it's what we're expending
> effort after to make a consolidated API set. So unless Nati and Ravi want to
> switch to using Swagger (or something else), WADL is the direction we're
> heading.

I'm voting WADL for sure :)

 I totally agree with Daryl that reading it is a PITA, and am
> finding (from my part) that the only definitive way to know about writing
> the docs and documenting the authoritative API is to read the underlying
> code. (which is what I suspect Nati likely did with the pull request that
> adds in WADL for the Nova/OpenCompute extension API)
> Nati - do you have your WADL parsing/reading code stashed in a public git
> repo somewhere that I could work with and help expand upon? I'd like to see
> what I can do to modify it to generate some of the interactive docs.

Sorry, It may takes time to open source it because of some paper works.
But it is just 300 lines script.

I used lxml.objectify
http://lxml.de/objectify.html

You can read wadl as python object.
It is very easy to generate something from the WADL if you know WADL structures.

xsd_root = objectify.parse("PATH2WADL").getroot()
xsd_root.resoruce_type  #get resource types
xsd_root .iterchildren()   #get childs
xsd_root.get('attribute') #get attributes


> On Oct 25, 2011, at 2:56 PM, Jorge Williams wrote:
>
> We've done quite a bit of work to get high quality documentation from a
> WADL,  in fact we are using some of this today.  We've taken most of the
> hard work re: parsing the WADL, at least for the purpose of generating docs
> from it and of writing code that can read it (though that later part can use
> a bit more work).
> We are also working to add WADL support in Repose, which we presented at the
> summit, you can find the presentation here:
> https://github.com/rackspace/repose/tree/master/documentation/presentations.
> The plan there is to have an HTTP proxy that can do validation of a service
> on the fly.  When it's done, you could, for example, turn this on when you
> run functional tests and get a gauge as to what your API coverage is and
> track both client and service API errors.
> Other API tools like Apigee and Mashery already have support for WADL.  In
> fact apigee maintains an extensive wadl library for common
> APIs: https://github.com/apigee/wadl-library.  There is some WADL support in
> python as well, though I haven't tested it first hand.
> So obviously, I'd vote for WADL.
> I haven't looked at Swagger too deeply, at first glance it *seems* to be
> missing some stuff -- but I'll have to study it in detail to be sure. (How
> do you define acceptable media types, matrix parameters, that a particular
> HTTP header is required?)
> I don't like the fact that it tries to describe the format of the message as
> well as the HTTP operations.  I'd rather take the approach that WADL takes
> which is to rely on existing schema languages like XML Schema and JSON
> Schema.
> What I do like about Swagger is that you seem to be able to generate some
> really cool interactive documentation from it.  I really like their API
> explorer feature for example:   You can see it here:
>  http://developer.wordnik.com/docs#!/account/get_word_lists_for_current_user.
>   That's pretty cool.  The thing is though, I could easily generate Swagger
> from my WADL :-)  So choosing WADL doesn't necessarily mean that we can't
> get access to those tools.
> Just my 2 cents,
> -jOrGe W.
> On Oct 25, 2011, at 3:24 PM, Anne Gentle wrote:
>
> Hi all -
>
> Would also love Swagger. Nati looked into it and he thought it would require
> a Python client generator, based on reading that "Client generators are
> currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript
> 3." So in the meantime the QA list and Nati suggested WADL as a starting
> point for auto-generating simple API documentation while also looking
> towards Swagger for a way to document a public cloud like the Free Cloud. At
> the last OpenStack hackathon in the Bay Area (California), Nati worked
> through a simple WADL reader, he may be able to describe it better.
>
> Hope that helps - sorry it's not more detailed than that but wanted to give
> some background, sounds like we all want similar outcomes and the resources
> for tasks to get us to outcomes is all we're lacking. QA Team, let me know
> how the Docs Team can work with you here.
>
> Anne
> Anne Gentle
> anne at openstack.org
> my blog | my book | LinkedIn | Delicious | Twitter
> On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <heckj at mac.com> wrote:
>>
>> 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
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack at lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack at lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>
>



-- 
Nachi Ueno
email:nati.ueno at gmail.com
twitter:http://twitter.com/nati




More information about the Openstack mailing list