Open Stack

(inline)

On Feb 6, 2013, at 6:26 PM, Gabriel Hurley wrote:

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

Yea, that's right. The issue is, however,  that unless you have someone maintaining the core namespace, it's hard to tell if the answer is "no".

For example,  I'm working on my own branch, or fork, or I have a different implementation.  I saw the same issue, you did, and I created the field called 'type' to fix it.  I used the values 'IPv4' and 'IPv6' and that's what my clients expect and use. From my perspective this is a totally backwards compatible change -- shouldn't mess anybody up.  

You come along, see the same problem, you're on a different branch or fork,  you're not aware of what I did,  but you decide to add 'type' but you choose values  '4' and '6'.  Now, my clients and your clients expect something different and if one wants to burst between our clouds then issues may arise.

Another problem,  your clients expect 'type' to be available, but I'm running an old version and it's not there. Now hopefully, the client is written so that it doesn't blow up in this case, but maybe not -- the expectation is that 'type' is available so not having it there may mess up the script.  In other words, there's nothing saying whether or not 'type' is in core.

So there's two ways to fix the problem.  Centralize control of the default namespace or use prefixes and keep things decentralized. 

1) If you have someone maintaining the core namespace you can tell that person, "hey, I wanna add 'type' and this is how it should work".  It's documented as an new feature (or an extension) and hopefully there's a way to detect that it's there. (easy for fields) The community decides no one else can mess with the default namespace, so there are no conflicts.

2) If you don't want to have a centralized person maintaining things, then if you prefix it with a namespace and make it an extension then there won't be a clash. Plus you send a message to folks that this is not something they should expect to always be there.

In this particular case, this may just be an oversight in the core spec. So I'd lean towards 1.

I think that this approach is way more powerful than full out  versioning, cus you always maintain backwards compatibility, (and forwards compatibility) and you don't need to keep track of minor version numbers etc. Plus, you can back out of changes.  If you decide a feature  is a bad idea, you can get rid of it, because you're detecting at the feature level rather than keeping track of an arbitrary  version number.


> 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
> 
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev