Open Stack

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?

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/