[Openstack] describing APIs for OpenStack consumers

Sandy Walsh sandy.walsh at RACKSPACE.COM
Thu Oct 27 19:25:54 UTC 2011 

We may need to change the way the implementations are written to require explicit keyword parameters. No more sneaking into the <body>. This may also mean that something more robust than the routes library may be needed?

Sadly, annotations of some form are probably going to be needed since we can't introspect the return types. The joy of dynamically typed languages.

Perhaps even parsing the doc string? Wait ... come back! As ghastly as it sounds, it does keep the interface definition with the implementation, so the likelihood of them going out of sync is lessened. I'm hesitant to suggest an external IDL form, but perhaps the other approach is to hand-craft the WADL and generate the code stubs from that? (not a fan)

-S

________________________________________
From: openstack-bounces+sandy.walsh=rackspace.com at lists.launchpad.net [openstack-bounces+sandy.walsh=rackspace.com at lists.launchpad.net] on behalf of Nati Ueno [nati.ueno at gmail.com]
Sent: Thursday, October 27, 2011 2:50 PM
To: Ziad Sawalha
Cc: <openstack at lists.launchpad.net>
Subject: Re: [Openstack] describing APIs for OpenStack consumers

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 at rackspace.com>:
> 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 at RACKSPACE.COM> 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 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

_______________________________________________
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

More information about the Openstack mailing list