Always keep in mind that there is only one truth in the 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 as easy as you may think, because out of your all clients, let's say you have total100 clients, there may exist some clients, say 25 clients, 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 clients and resist the change or do not modify the service then you may lose those clients who are asking for a modification, now what will you do?
Here, the versioning comes into the 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 preferring Windows 10, the newer version with more functionalities and modified UI, more.
Similarly, we can create different versions of the same service, our satisfied and older client can use the older version of the service, whereas the newer or unsatisfied client can consume the newer version. Thus, we will not lose, any client rather our relationship will be stronger.
Now, In web API, versioning doesn't mean method overloading or creation of new methods, it means a new controller for newer versions altogether.
Now the older and satisfied client will be using the service as they were using earlier with the same URL. But, they can upgrade to a newer version at any moment. 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 the previous article. we had an Employee controller with all the 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 the outside world the service is not brand new rather it's a newer version of the same service, so if we change the controller name like EmployeeGoldService then how the URL will look like:-
olderversion:- http://www.mysite.com/EmployeeService
newer version:- http://www.mysite.com/EmployeeGoldService
This is a damn bad idea, it looks like as if EmployeeService is completely different from EmployeeGoldService, in short, the service name for the 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.
As you can see from the figure, the Client has 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