← Back to team overview

openstack team mailing list archive

Re: describing APIs for OpenStack consumers

 

Generating WADL (or anything else) from code is fine, as long as we have the processes / tools (e.g., CI) in place to assure that a trivial code change doesn't make a backwards-incompatible change in what we expose to clients.

Do we?

(really, we should have these in place regardless of how things are generated)

Cheers,


On 28/10/2011, at 4:50 AM, Nati Ueno wrote:

> Hi folks
> 
> I tried to generate WADL from nova code.
> I could get all resource URI and method from Routes object.
> However, I could not get input parameters from code.
> (The api method accesses body argument directly. This is also bad for
> input validation QA effort.)
> 
> But If we use some annotations, it may be solved.
> Also, It looks possible to generate Resource definitions from model class.
> 
> 2011/10/26 Ziad Sawalha <ziad.sawalha@xxxxxxxxxxxxx>:
>> So you would do a diff if the generated WADL against the expected WADL. That would mean we use both. I think that's a reasonable approach.
>> 
>> 
>> 
>> On Oct 26, 2011, at 12:31 PM, "Monsyne Dragon" <mdragon@xxxxxxxxxxxxx> wrote:
>> 
>>> 
>>> On Oct 26, 2011, at 10:48 AM, Kevin L. Mitchell wrote:
>>> 
>>>> On Tue, 2011-10-25 at 15:30 -0700, Joseph Heck wrote:
>>>>> 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 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)
>>>> 
>>>> I wonder if it would be possible to generate much of the WADL from
>>>> introspecting the code itself...surely the URL structure itself can be
>>>> extracted from the paste setup, and the XML templates code I recently
>>>> contributed could easily be traversed to provide at least a basic
>>>> description of the output.  That could at least provide a starting point
>>>> for generating WADLs...
>>>> 
>>>> (Of course, I propose this, having little idea of what actually goes in
>>>> a WADL, but still... ;)
>>> 
>>> I've worked with WADL and WSDL before, and yes, it is indeed possible to generate the WADL by introspecting code. (with a few decorators/annotations assisting)
>>> This is what Sandy Walsh is suggesting, and I highly, highly recommend this approach.  Otherwise you have to either generate code from an external WADL, which makes the code a mess, or keep the WADL in sync with the code manually (bleh).  The big advantage of generating WADLs from the code is that you then get a machine-readable description of what the *code* thinks the interface is, not what you *hope* the interface is. That way,  if you look at the generated WADL, and if the interface isn't what it *should* be (as in "Where did THAT resource come from, and where did the foobar param on that GET method go?"), you know you have a bug to fix.
>>> 
>>> --
>>>    Monsyne M. Dragon
>>>    OpenStack/Nova
>>>    cell 210-441-0965
>>>    work x 5014190
>>> 
>>> 
>>> _______________________________________________
>>> 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
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

--
Mark Nottingham   http://www.mnot.net/





Follow ups

References