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

__________________________________________________________________________
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

Reply via email to