Open Stack

On 06/04/2015 05:27 PM, Lucas Alvares Gomes wrote:
> Hi Ruby,
>
> Thanks for starting this thread, just like you I've been always
> confused about when and when not bump the microversioning of the API.
>
>> Backwards compatible API adds with no user signaling is a fallacy
>> because it assumes the arrow of time flows only one way.
>>
>> If at version 1.5 you have a resource that is
>>
>> foo {
>>    "bar": ...
>> }
>>
>> And then you decide you want to add another attribute
>>
>> foo {
>>    "bar": ...
>>    "baz": ...
>> }
>>
>> And you don't bump the version, you'll get a set of users that use a
>> cloud with baz, and incorrectly assume that version 1.5 of the API means
>> that baz will always be there. Except, there are lots of clouds out
>> there, including ones that might be at the code commit before it was
>> added. Because there are lots of deploys in the world, your users can
>> effectively go back in time.
>>
>> So now your API definition for version 1.5 is:
>>
>> "foo, may or may not contain baz, and there is no way of you knowing if
>> it will until you try. good luck."
>>
>> Which is pretty aweful.
>>
>
> Oh, that's a good point, I can see the value on that.
>
> Perhaps the guide should define bumping the micro version something
> along these words: "Whenever a change is made to the API which is
> visible to the client the micro version should be incremented" ?

Ok, one more last thought on this topic: definition of visible change 
can go the wrong way even faster. E.g. remember that our JSON fields 
(instance_info, driver_info and even driver_internal_info) are part of 
API. Which means that we have feature-gate drivers :) and feature like 
cleaning as well (which we actually did via configuration option, 
despite everything said in this thread).

>
> This is powerful because gives the clients a fine grained way to
> detect what are the API features available.
>
> Cheers,
> Lucas
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>