Open Stack

On 07/07/13 10:12, Anne Gentle wrote:
> 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.

hmm, the wonders of our wiki never cease:
https://wiki.openstack.org/wiki/NovaApiValidationFramework

> 
>> (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 :)
>>
>>
>>