API Versioning for "compatible" changes

[roger peppe]

You could use minor versions for backwardly compatible changes.
That would cover backwardly compatible additions to fields
too, which aren't currently easily determinable using
the CodeNotImplemented approach.


On 30 September 2014 12:16, John Meinel <john at arbash-meinel.com> wrote:
> This came up recently in a discussion about the Uniter API, but I think it
> is a broader discussion that we should be having.
>
> If you are only adding a new method, it is possible to consider that this is
> a compatible change, and not bother to do the extra work to create a new
> version for that Facade and deal with multiple version compatibility.
>
> I would argue, however, that this is actually only half of the compatibility
> statement, and we actually make it harder for clients that want to use our
> API to do so properly.
>
> Consider if we have Client V1, and then we add a new method DoMagic(). If we
> create a V2 for it, then clients that want to use DoMagic can just do a "do
> you have Client v2?" and then decide right after Login what code path they
> want to use.
> Otherwise, they have to first check "do you have V1" because that is the
> first version that might have DoMagic, and then do the DoMagic call, and
> check if they get an IsCodeNotImplemented error, and then fallback to
> compatibility code.
>
> I do realize that there is overhead in doing this work. Especially given our
> current code base (with no versioning) most of our tests are not easy to
> apply to 2 versions of a Facade. However, as soon as we have 2 versions,
> we'll need the code refactored and then the third version should be much
> easier to create. So I think it is just a cost that we need to just do.
>
> The other axis for discussion is whether we go through this effort for all
> of our API, for only Client apis (and leave Agent APIs to really only have 1
> supported version). We did 1 supported version for Firewaller, because the
> new one can't get its job done with the old API.
>
> Thoughts?
>
> John
> =:->
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>