openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

The hard thing about processing a WADL is that WADLs uses links and references.

For example:  WADL A may refer to a method defined in WADL B, that's useful when you're defining extensions.  Or WADL A may define two resources that share GET, PUT, POST operations:  You see this with metadata in servers and images in the compute API /servers/{id}/metadata and /images/{id}/metadata, work exactly the same way, in WADL you don't need to define those operations twice you just link them in to different URIs.

Another issue is that there are different ways of defining resources.  You can take a flat approach, much like Swagger uses:

<resource path="/resource"/>
<resource path="/resource/level2"/>
<resource path="/resoruce/level2/level3"/>

Or you can take a hierarchical  approach:

<resource path="/resource">
   <resource path="level2">
       <resource path="level3"/>
  </resource>
</resource>

What's worse you can have a mixture of the two:

<resource path="/resource">
   <resource path="level2">
       <resource path="level3/level4/level5"/>
  </resource>
</resource>

The hard bit is that you need to resolve  all of those links and normalize the paths if you want to process the WADL.  We've (and by we I mean David Cramer),  created a command line tool that can process the WADL and give you a flat normalized WADL that does just that. There are options for flatting the path or expanding and resolving links etc.  The tool just runs the WADL though a couple of XSLT transformations and you end up with an easy to processes WADL on the other end.  You should run this as a preprocessing step, if you plan on writing a script to extract data.  We do this when we process the documents.

I know that the WADL normalizer is opensource but not sure where.  David, is it on github?

-jOrGe W.

On Oct 25, 2011, at 6:05 PM, Nati Ueno wrote:

> Hi Joe
> 
> 2011/10/25 Joseph Heck <heckj@xxxxxxx>:
>> 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@xxxxxxxxxxxxx
>> my blog | my book | LinkedIn | Delicious | Twitter
>> On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <heckj@xxxxxxx> 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@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
>> 
>> 
>> 
> 
> 
> 
> -- 
> Nachi Ueno
> email:nati.ueno@xxxxxxxxx
> twitter:http://twitter.com/nati