Tuesday, 6 August 2013

How to design backward compatibility and not turn your code into a mess?

How to design backward compatibility and not turn your code into a mess?

I am developing a Java-based RESTful web application intended to be a
centerpiece for its various client apps. Those client-apps can operate on
the same assets in the main system (e.g. client-app A creates assets in
main system, and client-app B fetches them from the system). We've rolled
out the /v1/ API version and develop new features in /v2/. The requirement
is to release v2, while still supporting backwards compatibility for v1
for some period of time, until all client-apps are ported to v2. The idea
behind this requirement is that client-apps potentially written against
different API versions should still be able to cooperate on the same
assets.
Currently, we cover both API versions within a single instance of the
system. While for some minor changes in HTTP API, it usually suffices to
provide a new controller (sth like a bridge pattern), for slightly bigger
changes it seems best to write a new controller & service layer (and
hopefully both versions will "meet" at some level, reusing a common set of
functionalities).
However, there are much broader changes to come. What's more, the main
system is not just a dumb CRUD, it's rather a complex multi-component
network, integrated with a handful of external services, involving some
async jobs' processing, etc. Certainly it's all but a convenient place for
keeping backward compatibility behavior-wise.
Are there any best practises to keep backwards compatibility of API &
behavior behind it, while not turning the code into a mess?
We do care about the quality of code, and hate polluting it with
copy-paste-adjust classes and maintaining duplicate/parallel feature
implementations. And yes, we have already divided the java packages for v1
and v2.
Also, we'd like to avoid the situation where the old version's code ties
our hands and keeps us from redesigning the new version's architecture,
just for the sake of simplicity of keeping this back compatibility.

No comments:

Post a Comment