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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
