API Versioning for "compatible" changes

[Dimiter Naydenov]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

Just to let you all know, the Uniter API facade is now versioned:
 - V0 - all existing methods except GetOwnerTag
 - V1 - a few new methods related to port ranges support added
   (AssignedMachine, AllMachinePorts, and ServiceOwner to replace
   the deprecated GetOwnerTag).

At the apiserver side, each version is in its own file (e.g.
uniter_v0.go, uniter_v1.go, with uniter_base.go containing common code
for both versions), and the same is true for the unit tests (e.g.
uniter_v0_test.go, uniter_v1_test.go, and uniter_base_test.go with
common tests shared between versions).

At the api (client) side, a BestAPIVersion method was added and used
internally to check if a method is available and returning an
errors.NotImplemented otherwise.

So please, from now on add new methods in V1. If something needs to be
removed or changed, and you're unsure how to implement it or test it
properly, ask me, Frank, or John, and we'll be glad to help.

I hope in the future more facades will get refactored like that, and
we can make the code and tests maintenance easier, as well as design
APIs with versioning and backwards-compatibility in mind.

Cheers,
Dimiter

On 30.09.2014 14:16, John Meinel 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 =:->
> 
> 

- -- 
Dimiter Naydenov <dimiter.naydenov at canonical.com>
juju-core team
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJULogSAAoJENzxV2TbLzHw8UYIALoqCSKAeDi/ticuMnMGfcwv
SYLRs6noCNGh/5Z2sGN1/Da9/4uQXPd6d99vEypZvWIl97J5aCtiHD8NKFYqrkwX
qTApprs0MEB9Ep1JJW6IZ7kGYL/3+HK7Bizv0CNmrkgvGSTnib2WC6RF4qduP+p3
2CiqBxBEwZ9bnCi21tX4Mbc4UFcbWHrILdE7KMOOQgpkjh/3TXHxfez968ZDuit1
JZ1lnudGwte6qqrPzJgyK4Mvc/MfpL9qxFJrwYzo5UNOwI9hg62EJMimHFmyUb0x
lTJ0/9MLYZD7iS5xsB/RovSV6FNp7oC/C34nMjUIVgxcbXRVMYWMKe25POXbkLI=
=f6gF
-----END PGP SIGNATURE-----