Open Stack

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

This is powerful because gives the clients a fine grained way to
detect what are the API features available.

Cheers,
Lucas