Open Stack

Something's been bothering me for a long time about the way OpenStack handles its APIs... There's a firmly-rooted idea in this community that touching a published API in any way, shape or form requires a complete API major-version revision.

That's how you halt progress. That's how you never fix problems.


To basic principles: why do we version APIs? To prevent incompatibilities. What causes an incompatibility? Changing key names, changing routes, changing methods, changing required or positional arguments, or changing the data type of values. Doing those things requires an API rev.

You know what's not incompatible? Adding additional non-conflicting data, and adding additional capabilities via query parameters. Those types of changes can be done with no impact on anything other than the strictest XML schema validators. To be polite you do a minor version bump so that consumers can identify specifically when a certain piece of data or capability became available.


But this idea that the APIs can never be touched has to stop. It's caused an explosion of "wild west"-style extensions in Nova that are unversioned unpoliced workarounds and hacks. It's caused features in Keystone and Glance to be delayed by one or more full releases.


I submit that the process is broken and we as a community need to embrace incremental API revisions to make our APIs worth using, 'cuz frankly right now they're a mess.


Sorry for the tirade,

    - Gabriel