REST API: Multiple versions, single application?

java rest versioning api-versioning
user3237736 picture user3237736 · Oct 24, 2018 · Viewed 9.6k times · Source

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

Sankarganesh Eswaran picture Sankarganesh Eswaran · Oct 24, 2018

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

Related questions

How to manage REST API versioning with spring?

I've been searching how to manage a REST API versions using Spring 3.2.x, but I haven't find anything that is easy to maintain. I'll explain first the problem I have, and then a solution... but I do wonder if I'm …

Read More
Main differences between SOAP and RESTful web services in Java

For now I have a slight idea about the differences between SOAP and RESTful services. My question is when I should use SOAP, and when I should use RESTful; which one is "better" when it comes to performance/speed or …

Read More
JAX-RS — How to return JSON and HTTP status code together?

I'm writing a REST web app (NetBeans 6.9, JAX-RS, TopLink Essentials) and trying to return JSON and HTTP status code. I have code ready and working that returns JSON when the HTTP GET method is called from the client. Essentially: @Path("…

Read More