Open Stack

On Jan 18, 2015, at 9:25 PM, Jay Pipes <jaypipes at gmail.com> wrote:

> On 01/13/2015 07:41 AM, Sean Dague wrote:
>> On 01/09/2015 04:17 PM, Everett Toews wrote:
>>> One thing that has come up in the past couple of API WG meetings
>>> [1] is just how useful a proper API definition would be for the
>>> OpenStack projects.
>>> 
>>> By API definition I mean a format like Swagger, RAML, API
>>> Blueprint, etc. These formats are a machine/human readable way of
>>> describing your API. Ideally they drive the implementation of both
>>> the service and the client, rather than treating the format like
>>> documentation where it’s produced as a by product of the
>>> implementation.
>>> 
>>> I think this blog post [2] does an excellent job of summarizing the
>>> role of API definition formats.
>>> 
>>> Some of the other benefits include validation of
>>> requests/responses, easier review of API design/changes, more
>>> consideration given to client design, generating some portion of
>>> your client code, generating documentation, mock testing, etc.
>>> 
>>> If you have experience with an API definition format, how has it
>>> benefitted your prior projects?
>>> 
>>> Do you think it would benefit your current OpenStack project?
>> 
>> It would hugely benefit OpenStack to have this clear some where that
>> was readable.
>> 
>> I don't specifically have experience with these, my only feedback
>> would be make sure whatever format supports having multiple examples
>> per API call referenced or embedded.
>> 
>> My experience is that API specs aren't typically fully read and
>> injested. Instead examples are used to get some minimum working
>> code, then bits are spot referenced and evolved until the client code
>> looks like it does what was expected. So providing multiple examples
>> per API will help more people wrap their head around the interface in
>> question.

In my experience developing client tools for OpenStack for the past 2 years, the examples are useful but, sooner rather than later, I find myself needing the full API definition (I’m avoiding the word spec because it’s overloaded in OpenStack land already).

The reason the OpenStack API examples are so useful is because they include details that really should be part of the definition. So often I find myself looking at an example and wondering where a param came from and its possible range of values only to find no mention of that param in the definition.

I’m definitely +1 to multiple examples per API but those examples need to be built on top of proper API definitions. I’d like to see us move away from an API documentation second mindset to an API definition first mindset. Having the API definition drive the implementation of the client and the service.

> This is spot-on, Sean.
> 
> I would support making Swagger the API definition format for OpenStack APIs. I think it's by far the best of the bunch, in my experience, and I've used API Blueprint, Swagger, and RAML.
> 
> Best,
> -jay