Assume you need to define a completely new REST API for a given service. These rest APIs are distinguished by something like "v1" and "v2" in the path.

If you develop these services in Java, would you:

  1. Add the new access points to the given project and deploy a new version that supports both the v1 and the v2 paths?
  2. Remove all the v1 access points from the project, add the new v2 access points and deploy two different versions of your service simultaneously on your server?

Solution 1 has the disadvantage that it is difficult to update library versions because all changes need to be made for both APIs. Solution 2 has the disadvantage that you have two productive versions of the same service which might be confusing. Additionally, fixing bugs means fixing two programs.

  • I'm not sure how these things look like in Java environment, but how we used to this is using ASP.NET WebApi2: we install one instance of the API, which serves both v1 and v2. We deploy the v1 using the [Obsolete] attribute to indicate clients that this version will be deprecated in future, and allow them some time (of course it's clearly communicated how much) to use the v2. – kayess Sep 14 '18 at 10:20
  • Seems to me that either approach is viable, but decisions like this are typically driven by business needs. Versioning mostly impacts consumers. – Dan Wilson Sep 14 '18 at 11:05
  • @DanWilson From the outside, both solutions will look the same. Both v1 and v2 are visible. The difference is purely in structure and maintainability. – J. Fabian Meier Sep 14 '18 at 11:11
  • 1
    Note also that you should have a plan to migrate all your clients from v1 to v2 and eventually deprecate and shut down v1 (or stop supporting altogether, at least). If this is a private/internal API, all that should not be too hard. – Darkhogg Sep 14 '18 at 11:57
  • 1
    My first instinct is that this would be mistake. You shouldn't have two versions of your-service, both APIs should depend the same version. You should think of an API as a dumb layer on top of your actual business logic. If the actual business logic changes, then obviously your API should use the most recent version at all time. I have a feeling that you coupled the v1 too tightly with the business logic, resulting in difficulty to separate a clear, distinct API out of it, and this is leading you to an incorrect architecture when you realised the v1 did not fulfill your needs. – Vincent Savard Sep 14 '18 at 12:14

I'm a big fan of backwards compatibility generally, and managing end of life of a service as a first class concern, so

  • By preference: if it is possible to extend the interface without breaking existing clients, then go ahead and do that.

  • If it is not possible, then deploy a new service with the new interface, and end of life the old service.

If you want to break with the past, use a different hostname, with new branding! -- Fielding 2013

So end of life here really means something like advertising that the legacy service has been deprecated, and communicating to consumers when support for the new service ends.

I sometimes think of the contract between service and consumers as a subscription -- when consumers subscribe, they are given a promise that the service will continue to be available until some fixed point in the future, and the understanding that they can renew the subscription.

(Subscription isn't a great term, because we aren't really talking about billing here, so much as a guarantee that the service will be available until at least $DATE).

It may help to review Pieter Hintjens: The End of Software Versions.

The first step to enlightenment is to see that contracts have a life-cycle. This applies to all contracts, both in software and in the real world. The contract life-cycle is not an invention, it's a feature of real world economics, and a useful one for software engineering.


You should deploy a server which supports BOTH v1 and v2, to give time for clients to migrate their API usage (so what you called option 1).

How many old versions you support, and for how long, is a function of your business practices, how quickly you transition between versions, how quickly you transition clients (client software), and the costs of breaking client software due to version skew (a client that counts on v1 breaks because you got rid of support for v1).

A good rule of thumb from my experience (maybe says more about the businesses I worked in - may not apply to yours) - is to maintain backward compatibility for a year or two.

Note also - I always rewrite my API implementation for v1 (once I have v2 available) to simply INDIRECT/CALL the v2 API. This reduces the code duplication and makes it clearer just what the differences are between the versions of the APIs.

  • This doesn't really answer the question. Both of OP options behave the same from the outside. – Esben Skov Pedersen Feb 26 at 17:15
  • @EsbenSkovPedersen I edited the response to make it more clear. It is a clear and direct response to his question. He said "should I do a or b" and my answer was "a" and here is why (and a few hints how). – Lewis Pringle Feb 26 at 17:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.