Demystify Web API Versioning

Since technology is evolving every day, you may have the opportunity to upgrade your existing business needs and this tutorial is about WebApi Versioning using Routing. Once you have published a successful API, the client/consumers will start depending on it, but change is required as business grows. Requirements are being changed every day and here the idea occurred to me to create a new API without tampering with an existing one. There are various ways to do this, like URL, Custom header, Query String and Accept Header.

Web API Versioning using URI

First, I will cover WebApi versioning using an URL in this section before proceeding. I’d like to share one of the possible situations when you may need this. So let’s dive into it in a practical way.

You might have a situation in which you already have a running WebApi hosted on a server and plenty of end users are getting its benefits. For an example, here the current API is returning a response in JSON format as shown below:



Down the line, the customer may desire to have a few more things without messing with the existing one. After considering a new requirement, the client needs a few more fields from the same API to maintain their policies at the business level, so now we can consider a new version of the API with a few more fields like City and Gender in employee in response as depicted below:



To do this we’ll set a new route for the new version of the WebApi Version number in the URI, considering the most common way of versioning so we can consume a resource by calling http://localhost:57888/api/v1/Employees/FetchEmployeeById/1 (the client wants to use version 1 of the API) or http://localhost:57888/api/v2/employeesv2/FetchEmployeeById/1 (the client wants to use version 2 of the API).

To implement this we need to add two new routes inside the Register method in the “WebApiConfig” class as in the code below:



Notice in the code shown previously there are two new routes and mapped each route with its corresponding controller. In other words, the Route named “Version1? is by default mapped to the controller “Employees? and the Route named “Version2Api” is mapped to the Controller EmployeesV2.

Assume we want to add a new version, V3, of the existing WebApi. Then we need to add a new route to WebApiConfig.cs and so on.

Before proceeding I’d like to share how WebApi selects an appropriate controller from the current request. There is a class DefaultHttpControllerSelector that has the method SelectController, that method has the parameter HttpRequestMessage to maintain the information of route data including controller name defined in the class WebApiConfig. Based on this information it fetches the controller/classes collection using reflection derived from the ApiController base class.

The following is a code snippet for CustomControllerSelector:
Add “CustomControllerSelector” to WebApiConfig.cs to get its benefit as shown below:
Code snippet for Version v1

Kindly find the code below for the EmployeesController class and Employee Model class that represent version v1 of the WebApi as shown below:

To test this please press F5 and run you WebApi.



To test this we need to issue a GET request using the Web Proxy tool Fiddler as in the image below. Kindly copy and paste the following URL that specifies version v1:
http://localhost:57888/api/v1/Employees/FetchEmployeeById/1



Code snippet for Version v2

Kindly find the code below for the EmployeesV2Controller class and EmployeeV2 Model class that specifies version v2 of the WebApi: