Open Stack

It's all about balance.  If "wild-west" style extensions turn into "wild-west" style core API changes, then we're in really bad shape.

Keep in mind that a client may have to live in an environment where it has to interact with multiple deployments with different versions and different set of extensions etc.

We talked a lot about versioning on the list.  There were a lot of really good ideas thrown out there.  

We've also talked about having extensions in the default / unprefixed namespace so that they look like new core features but can be detected at runtime.

In my opinion the fundamental principles that we need to stick to are:

1.  The core contract should be strict and implemented / supported by all environments.
2.  New features, should not be incompatible with the core contract.
3.  New features should be detectable -- ie because they are extensions.
4.  New features should not collide with each other.  For example if HP introduces a password reset feature in keystone and RAX introduces a password reset features that doesn't work the same way then those two should not interfere with each other (so there are cases where we should use prefixing).
5.  The PTL has the right to promote any extension so that it doesn't need to be prefixed, but should track what these are, and thus should control the non-prefixed (default) namespace.

In my opinion we don't need versioning unless we have a change that is truly incompatible with the core contract. And honestly I would avoid these sort of changes.  Instead I'd rather have changes in the default (non-prefixed) namespace, that are detectible at runtime.  And have all of these changes be compatible with the core.  This to me is a much smoother than have folks rewrite to a new API version frequently -- you can consume new features as is, when you detect them.


-jOrGe W.


On Feb 6, 2013, at 5: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.
> 
> 
> 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