Open Stack

More below.

Anne Gentle
Content Stacker
anne at openstack.org


On Jul 6, 2013, at 7:39 PM, Tom Fifield <tom at openstack.org> wrote:

> On 06/07/13 23:16, Anne Gentle wrote:
>> On Sat, Jul 6, 2013 at 5:41 AM, Tom Fifield <tom at openstack.org
>> <mailto:tom at openstack.org>> wrote:
>>    You have probably seen the discussions on the development mailing
>>    list regarding the nova v3 API. It brings some significant and
>>    exciting changes that we obviously need to document and share with
>>    the world :)
>> 
>>    Yesterday, I had the opportunity to chat with Chris Yeoh, who's been
>>    spearheading the effort, about what it's going to take to document
>>    nova V3 properly.
>> 
>>    Chris, like many, is a fan of our api reference (however, noting
>>    that incompleteness makes people sad :|), and is keen to see it succeed.
>> 
>> 
>> Incompleteness for Compute? Or is it that Identity v2 and v2 are in the
>> process of being added? Or? Anything else missing? Need bug references. :)
> 
> As you know, I'm a fan of the "bugs or it isn't true" response too :)
> 
> However, in this case, since we're publishing the definitive reference
> on something that can actually be tested to be complete - we should have
> higher standards. Right now, the truth is, we have no idea how complete
> the API reference is. The only way we have to find out is to sit down
> with a beverage of some description and methodically work through a ton
> of code and a ton of WADL.
> 
> I guess Grizzly was our first attempt at tracking these, with DocImpact,
> and the fact that there are still 14 of those bugs unfixed (yes,
> including one for compute API - #1084500) means we are incomplete :)
> https://launchpad.net/openstack-api-site/+milestone/grizzly
> 
>> 
>> 
>>    After walking through how the API reference document is produced
>>    right now, our conclusion is that to properly write up the nova V3
>>    API is going to be "a lot of work".
>> 
>>    As such, I'd like to start a discussion about our methodology for
>>    producing the API reference document, and possible ways we can
>>    improve it, potentially remove some of the manual steps, and
>>    integrate some of the changes nova has made in its sample file
>>    generation.
> 
> So, here's my question. If we put some more instrumentation in the nova
> code, is it possible to generate the WADL files automagically?
> 

Neutron had a reasonable start to this end goal. Any neutron folks want to give some input? 

> If this is too complex to achieve in this release cycle, is there at
> least a way we can at least write some code to test if the WADL is
> complete or not?
> 

Sounds like a good idea.


> (I agree completely that getting sample responses/requests in an
> automated manner is a nice low hanging fruit and a good place to start
> regardless)
> 
>> 
>> I've been liking the Swagger API standard. Is there interest in
>> investigating? 
>> 
>> https://github.com/wordnik/swagger-core/wiki
> 
> The output looks pretty :)
> 
> 
>