Open Stack

Thanks Jorge. That's a more encompassing view than what initially set me off today, which was as insignificant as adding the overlooked "type" field to the IP addresses in the Nova server addresses list.

When an API change is proposed, the question should not be "is this changing a published API?", the question should be "would this change cause pain for anyone consuming this API?". If the answer is a unanimous "no", then why would we block changes that hurt no one and benefit the whole?

All the best,

    - Gabriel

> -----Original Message-----
> From: Jorge Williams [mailto:jorge.williams at rackspace.com]
> Sent: Wednesday, February 06, 2013 3:59 PM
> To: OpenStack Development Mailing List
> Subject: Re: [openstack-dev] "Changing" an API
> 
> 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
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev