Open Stack

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.

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