API Versioning for "compatible" changes

[John Meinel]

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
=:->
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140930/cfbc04f4/attachment.html>