Open Stack

On 02/07/2013 06:50 AM, Sean Dague wrote:
> 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.

Can of worms coming:

What if learn from autoconf and get rid of declarative version knowledge
in favor of a richer capabilities model? We're already doing this on a
small scale. We ask "do you have security-groups" and either enable it
or disable it. What if we could ask "do you have security-groups.foo"?
Then the only thing that needs a _version_ is the mechanism for
capabilities introspection itself...

I should mention, I'm on jetlag ...