Open Stack

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.

	-Sean

> 
> Thanks,
> Everett
> 
> [1] https://wiki.openstack.org/wiki/Meetings/API-WG
> [2] http://apievangelist.com/2014/12/21/making-sure-the-most-important-layers-of-api-space-stay-open/
> 
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 


-- 
Sean Dague
http://dague.net