REST API: Multiple versions, single application? [closed]

Question

I am working on a REST API where I will have to introduce some breaking changes soon, so a v2 is needed. We still need to support v1 for a couple of months though in parallel, to give our clients time to switch over to the new API whenever they are ready. Our API is offered via shared cloud, and all our clients share the same system backend, especially a single, shared database.

I have found a lot of articles about REST API versioning, but they were all more from a client's point of view, or high-level design point of view. That's not really my concern, our API already has a versioning in the URI, so offering services with a /v2 base path won't be aproblem.

However I am asking myself how I am actually going to implement this, and I haven't really found good articles on that. I don't really want to branch off a v2 of my project and then build and deploy v1 and v2 as separate applications, because then I would have maintenance, bugfixing, configuration changes etc in two applications, which is double work and carries the usual dangers of redundancy (i.e.: possible inconsistencies between the versions). Also, the v2 of course is not different in every service, so most of the code would still be the same.

Is there any best practices on how to technically implement a REST API in a single application that provides multiple versions to the outside, and where some code is shared (i.e.: v2/someService would internally redirect to v1/someService), and just the actual differences are coded in new services? Maybe there's even frameworks that help with designing this? The app is coded in Java with Spring MVC if that's helpful.

I'm thankful for any tips or resources on how to tackle this. Thanks!

Answer 1

Hope you have seen

1. API design ensuring backward compatibility
2. http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf

Having two versions of API in the same application is quiet enough

api.mysite.com/[version1]/api/url

api.mysite.com/[version2]/api/url

Not sure why you need to build and deploy v1 and v2 as separate applications? Unless you are planning for a Zero-Down-time rolling upgrade in production

Answer 2

I like to bring up the following strategies into the discussion, both are strategies in Continuous Delivery.

Branch Abstraction

The basic idea is to place an abstract layer in between the clients and your current implementation. Then introduce a second implementation behind the abstract layer. This gives you the opportunity to progress within your normal code base but support new features for your next version API instantly.

https://martinfowler.com/bliki/BranchByAbstraction.html

Feature Toggles

Add features to your code base without making them visible to your customers. This allows you stay on your main development branch even if things are not ready for end users yet.

https://martinfowler.com/articles/feature-toggles.html