Posted on 5/15/2020 9:01:11 PM by Admin

Web API Versioning

Always keep in mind that there is only one truth of universe, and it is "Change is the only constant". Meaning, suppose today you have 30 clients ,who are consuming your web api service, tomorrow it may grow to 1000. Similarly today all your clients are satisfied with your service but tomorrow their business may grow and they can ask you to modify the service.

But, modifying an existing web API service is not easy, cause out of your all client let's say 100 ,there may exist some client suppose 25 client ,which may be completely satisfied with your service and any change in your api services may break their application.

But if you will just focus on your 25 client and resist change or do not modify the service then you may lose those clients who are asking for modification, now what will you do?

Here the versioning comes into picture, for example today we have windows 10, it doesn't mean window 7 is obsolete, no ,not at all, people are still using windows 7.But new customers of Microsoft windows are more preferring windows 10, the newer version with more functionalities and modified UI.

Similarly, we can create different version of same service ,our satisfied and older client can use the older version of service ,where as the newer or unsatisfied client can consume the newer version. Thus, we will not lose ,any client rather our relationship will be more stronger.

Now ,In web API ,versioning doesn't mean method overloading or creation of new methods ,it means a new controller for newer version altogether.

Now the older and satisfied client will be using the service as they were using earlier with same URL. But ,they can upgrade to newer version at any moment of time. Meaning clients are free to use any version of the service with terms and conditions (if there any).

Let's take the example of EmployeeService of previous article. we had Employee controller with all necessary methods, now if we want to create a new version of this service then we have to create a new controller, but we have to keep in mind that for outside world the service is not brand new rather it's a newer version of same service , so if we change the controller name like EmployeeGoldService then how the url will look like:-
  olderversion:- http://www.mysite.com/EmployeeService
  newerVersion:- http://www.mysite.com/EmployeeGoldService

This is damn bad idea, it looks like as if EmployeeService is completely different from EmployeeGoldService, in short the service name for outside world shouldn't change rather the client should have options to specify which version of the service they want to consume , and its developer duty how they return different version of the service depending upon the version number.

Web API Versioning
Web API Versioning

As you can see from the figure ,Client have the following options to specify version number (web API versioning technique).


  1. with URI
  2. with QueryString
  3. with Custom Version Header
  4. with Accept header
  5. with custom media types