Open Stack

Hi Gabriel,

I 100% agree that changes which are totally backward compatible should be allowed rather than bifurcate the APIs with extensions which cause the clients and language bindings grief. Backward compatible changes with a minor version bump is the logical thing to do.

The more general problem is lack of any real API guidelines across all APIs, including versioning as you point out. There exists a relatively small set of guidelines which would solve much of the API mess. My feeling is that all API related decisions are totally up to the PTLs who can do whatever they like. And they do. So we have some API patterns which are good, some bad, and some totally different. In the past there has been push back on creating common API guidelines so I guess I am not totally surprised of what we are seeing.

Peter.

-----Original Message-----
From: Gabriel Hurley [mailto:Gabriel.Hurley at nebula.com] 
Sent: Wednesday, February 06, 2013 3:39 PM
To: OpenStack Development Mailing List (openstack-dev at lists.openstack.org)
Subject: [openstack-dev] "Changing" an API

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


_______________________________________________
OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev