There is a need to modify the existing contract (request/response payloads), of a Spring Boot Microservice, which are essentially breaking changes (not backward compatible). And it is essential to support both the versions of the contract till some time - till the time all the clients upgrades themselves to the newer version.
In order to achieve this, it has been decided to use URL versioning strategy (like /v1/{resource} and /v2/{resource}).
Now, the question is what is the best way to implement this in code? Below are the two proposed solutions
Branch out the version one (/v1) code and maintain it separately till this version is supported. This essentially means that cutting the branch from master and build/deploy from this branch and maintain two instances of the same service each supporting v1 and v2 versions respectively.
In the same master branch, introduce a separate package (like service.api.v2.request) and put all the api payload request/response classes in there and introduce a new endpoint controller to support (/v2). This approach enables single instance to support both the versions.
Which one of the above is a better approach? Or is there any other standard/better alternatives to achieve this? Does Spring Boot provides any out of the box support for such needs?
It depends how much commonality there is behind the controller. If the versions are significantly different all the way through to the back end then maybe different branches are easier to work with, but if the main differences are in the controller paths and the input and output objects involved in those methods, then 2 branches will likely lead to the pain of applying changes to both, and remembering to do so every time - it's the kind of situation where sooner or later an important fix will be missed.
It's all a balance, and you need to weigh up the maintenance cost of the approaches in your case in terms of time and effort, and also risk of mistakes, as well as the cost of separate deployments.