Web API Versioning (using NameSpaceControllerSelector) – Part 1



In this article, I am going to discuss Versioning of Web API, its needs, approaches used for versioning and how we can implement that.

Why we need Versioning?

API versioning is very much required if we are exposing our services for the public, so it need to be our API should be forward and backward compatibility. By versioning, API  don’t affect the existing functionality and break user application which depends on our API.

How we are going to do this?

In the Web API default routing implementation map routes to the controller by ControllerClass name. Internally Web API select controller, for route, through DefaultControllerSelector which implement IHttpControllerSelector.SelectController. Using default controller selector we can’t really version web API, but we can implement our custom selector to select right version of our controller. We can easily create a custom HTTP controller selector by implementing IHttpControllerSelector.

What approach should be used to versioning the Web API?

Currently within the software community, there are four basic approaches where we can do versioning in a REST API:

  1. In URI, with this approach URI will be
  2. In URI parameter, with this approaches
  3. Content Negotiation This is done in the HTTP header.
    Accept: application/student-v3+json
    Content-Type: application/student-v3+json
  4. Request Header This is also done in the HTTP header.
    x-student-version: 2

Majorly, today there are two different method are used for Web API versioning.

  1. URI based versioning
  2. HTTP custom Header based versioning


Notes: On the web, we can find many argument for using each of these, and even combinations of these, different approaches. To determine which approaches best fits your current project, you should research this on your own.


In this article, I am going to implement first approach that is URI based versioning.

Our API URI will be /api/{apiversion}/student

So for URI based versioning I am going to create NamespaceHttpControllerSelector which implement IHttpControllerSelector.


Implementation of versioning

First create a new Web Application project with Web API template, and add two folder named V1 and V2 in Controllers folder. Then add Web API 2 Controller in both folder (V1 and V2). My API controller name is StudentController. Now my solution is look like:

Till now our solution have 2 StudentController classes in different namespaces. However, request will always be routed to the controller in ApiVersioning.Controllers.V1 namespace because the framework only matches on the controller class name without regard to the controller class’s namespace, and the V1 controller is the first match it finds. This is the case with both convention-based and attribute-based routing.

To overcome this, we will use attibute based routing with custom contraints, and we will also add a custom controller selector that first match the namespace when looking for controller class.

First, we will create constraints. So create a folder name Routing in solution and add a class named VersionConstraint.cs to it.


The main purpose of these two constraints classes is to keep unique the route URI.  We need to ensure globally unique route names, as required by ASP.NET Web API. In these class we implements the IHttpRouteConstraint.Match method. It will return true if the specified parameter name equals the AllowedVersion property, which is initialized in the constructor. It get this value from a RoutePrefixAttribute, which we will decorate in our controller.

In ApiVersioning.Controllers.V1

In ApiVersioning.Controllers.V2

A Custom IHttpControllerSelector

My controller selector implementation was inspired by Mike Wasson’s MSDN blog post. The implementation taken heavily from the official Microsoft CodePlex NamespaceControllerSelector sample referenced in that blog post. I made some modification, but the basic design and implementation comes straight from CodePlex.

Add a NamespaceHttpControllerSelector.cs class in routing folder.


Here a lot thing going on in that controller selector, and it’s explained well in Wasson’s blog post, so I will recommend you to dwell on this topic.

Configure the API

Now we are ready to test our API, but after register our constraint with ASP.NET Web API so that it gets applied to incoming requests. We also need to configure our custom controller selector. We accomplish this by implementing the WebApiConfig class as follows:


Run the API

Now run the API

API V2 request and response:

That’s great. We learned about routing, including many of the functionality made available by
ASP.NET Web API 2. Also we learned about constraints and controller selectors. Now we are going to implement API Versioning by Header. in next post.

A hope

I hope that you will have better understanding constraints, routing, and controller selector. I would like to hear valuable feedback or question from you. It encourage me to write more quality article.

Happy Reading and Coding:)


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s