On 01/09/2015 04:17 PM, Everett Toews wrote: > One thing that has come up in the past couple of API WG meetings  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  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 > >  https://wiki.openstack.org/wiki/Meetings/API-WG >  > 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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Sean Dague http://dague.net __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev