Open Stack

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?

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?

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