Open Stack

On 02/06/2013 06:39 PM, Gabriel Hurley wrote:
> 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.

It's a problem if you have a client which expects those parameters, is 
pointed against an implementation that doesn't have them, and now 
behaves incorrectly.

Versioning isn't just about old clients talking to new servers, it's 
also about new clients talking to old servers from potentially different 
vendors that say they are the same version of the API, but don't take 
the same parameters.

> 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.

100% agreed on Nova extensions wild west. We have to get better there. 
It's a complicated beast though. Mauro and I spent a lot of time doing 
API audit on Nova in this cycle, and it turned into a much bigger beast 
than we were expecting (hence the delay of v3 into havana).

The Nova v3 API discussion at havana summit is going to need to include 
something about extension versioning in it, because the pile of nova 
extensions are definitely a mess. I don't think you'll get anyone to 
disagree with you there. :)

> 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.

Incremental versioning is it's own beast (just look at the number of 
versions the Nova RPC API has during a release :)), but I'd love to hear 
a more concrete approach here. It's harder to work out in the abstract.

My concern is only that clients have enough information to know what 
they are talking to, and how to make the right calls.

	-Sean

-- 
Sean Dague
IBM Linux Technology Center
email: sdague at linux.vnet.ibm.com
alt-email: sldague at us.ibm.com