Add ASP.NET Web API support to an existing ASP.NET MVC Web Application

Custom Routing and Action Method Names in ASP.NET 5 and ASP.NET MVC 6

One of the most interesting updates of the new ASP.NET Core platform (also known as ASP.NET 5) is the fact that it merges the old MVC and Web API frameworks into one (MVC 6). This allows you to have the best of both worlds: the rich features of the former MVC Controllers - with each methods returning an ActionResult - together with the versatility of the ApiControllers, whenever we need to return pure HTTP response types such as IHttpActionResult, HttpResponseMessage and so on. This basically means being able to serve Views and/or WebServices whenever we want to, without having to change your overall approach.

What if we need to do that in a plain old ASP.NET 4 MVC-based application? As a matter of fact, we can do that there too: any standard MVC Controller can be tweaked to make it act & behave just like an ApiController: we just need to develop our very own ActionResult classes and everything will more-or-less work like we're expecting to. However, such an approach can be very hard to maintain and test: on top of that, having MVC Controllers methods returning ActionResult mixed with others returning raw/serialized/IHttpActionResult data can be very confusing from a developer perspective, expecially if you're not working alone.

Luckily enough, there's a nicer alternative: we can import (and properly configure) the core ASP.NET Web API package into our MVC-based Web Application: this way we'll get the best of both worlds, being able to use the Controller  and/or the ApiController  classes together, as long as we need to.  To do that, we just have to manually install the required components of the Web API framework that we normally miss in a MVC4 or MVC5 project. This post will explain how we can do that in few easy steps.

Install the Web API NuGet packages

The first thing to do is to install the latest version of the ASP.NET Web API package. We can do that by opening the Visual Studio's Package Manager Console and issuing the following NuGet commands:

For further references regarding ASP.NET Web API package we can also read we can refer to the official documentation.

Create a sample Web API Controller

Once we imported the required packages we can add an ApiController to our existing ASP.NET MVC project. The ApiController is the base class for the ASP.NET Web API controllers: the most relevant difference between a MVC Controller and an ApiController is that the latter is specialized in returning data: just to make an example, they can transparently serializing the data into the format requested by the client. It's also worth noticing that they follow a different routing scheme, providing REST-ful API routes by convention (that can be changed using Attribute-based routing, as explained here).

Here's a sample (and working) ApiController: the syntax slightly changes depending if you're using Web API or Web API 2:


Web API 2

We can either copy the above code in our /Controllers/  folder or creating one from scratch to suit our needs.

Define a Web API Routing Configuration

The next step involves implementing Web API in our existing MVC-based routing configuration. We can do that in two ways: add a Web API configuration file (the suggested way) or override the existing routing configuration of our MVC Web Application.

Adding a WebApiConfig.cs file

If we want to enforce a "separation of concerns" between MVC and Web API, This is our best choice. From Solution Explorer, right-click to the /App_Start/ folder, then add a new C# class file naming it WebApiConfig.cs with the following contents:

NOTE: In case you don't have the /App_Start/ folder, any other folder will also work, as long as you'll add the relevant namespace reference to the Global.asax.cs and/or Startup.cs file when you'll have to register it (see below for details).

This will ensure that every requesting URL starting with /api/ will be routed to our Web API controllers and handled by them.

Adding a Web API rule to RouteConfig.cs file

Alternatively, we could also add a WebApi-specific rule to the RouteConfig.cs file, which controls the MVC routing rules. We can do that in the following way:

The benefit of doing that is that we can skip the following paragraph, as we don't have anything new to register, at the cost of mixing the two. On the other hand, we'll have the two worlds intertwined into one, which can lead to confusion. Altough this is mostly a developer choice, we slightly recommend the following approach.

Register the WebAPI Routing Configuration

If we chose to add a new WebApiConfig.cs file, we need to register that on our Web Application's main configuration class. This is most likely the MvcApplication class within the Global.asax.cs file, which Application_Start method needs to be changed as follows:

If we're using the OWIN Startup template instead, we need to do the same in the Configuration method of the Startup class, which is defined withinin the Startup.cs file:

 Testing it up

That's it. Now we have the best of both worlds into the same Web Application. We can easily test it up by requesting the following URLs:

Notice the last URL: we added it as an example to demonstrate how is possible to mix the default Web API RESTful conventions with custom action methods using attribute-based routing.

That's it for now: happy routing!


About Ryan

IT Project Manager, Web Interface Architect and Lead Developer for many high-traffic web sites & services hosted in Italy and Europe. Since 2010 it's also a lead designer for many App and games for Android, iOS and Windows Phone mobile devices for a number of italian companies. Microsoft MVP for Development Technologies since 2018.

View all posts by Ryan

4 Comments on “Add ASP.NET Web API support to an existing ASP.NET MVC Web Application”

  1. Ryan, this is exactly what I was looking for. The problem you cleared up for me was changing my controller type from Web MVC Controller to an API Controller. After that it took me 5 minutes to wire up my EF model and I was done.

  2. Thanks a lot for your explanation. Cleared up a lot of things for me!
    Almost ended up using regular Controllers for my API calls.

    Some troubles I had with:
    public HttpResponseMessage Get()
    return “It works!”;
    didn’t work. This worked:
    public IHttpActionResult Get()
    return Ok(“It works!”);

    2) Routing in the same RouteConfig.cs file didn’t work. I kept getting 404 error.
    When I used the 2 file configuration it worked.

    1. Hello,
      my guide was originally for Web API, yet it seems to me that you’re using Web API 2 since you’ve IHttpActionResult available.

      I updated it accordingly to support Web API 2 as well, as per your suggestion. Thank you for helping me to make a better guide!

      Regarding the RouteConfig.cs, I couldn’t reproduce the error but I guess that the issue is most likely the same (Web API 2 different ways of handling routes).

  3. Pingback: ApiController和ASP.NET的MVC控制器之间的差异 – CodingBlog

Leave a Reply

Your email address will not be published. Required fields are marked *

The reCAPTCHA verification period has expired. Please reload the page.

This site uses Akismet to reduce spam. Learn how your comment data is processed.