Building a Web API 2 project from scratch using OWIN/Katana .NET Part 1

Introduction

If you’re a .NET developer then you must have come across the new light-weight web framework standard called OWIN. Its implementation by Microsoft in .NET is called Katana. We’ve looked at OWIN/Katana on this blog already starting here. I won’t go through the same exact same topic in this new series. Instead we’ll concentrate on the basic components that are required at a minimum to build a functioning, platform independent Web API 2 project.

If you’ve read other posts on this blog then you’ll know about my preference for web services as opposed to shiny GUI development á la ASP.NET MVC. Also we’ll be looking into other Web API 2 features in OWIN later on so this will be a good foundation.

One primary goal of OWIN/Katana is to enable you to deploy the web-based project on a variety of hosts. Traditional ASP.NET applications are tied to IIS through the large System.Web library. It was impossible to develop a working enterprise web application without System.Web and IIS before OWIN/Katana came along. Now it’s perfectly feasible to host your application on other platforms and we’ll see examples on how to do that in this series.

Initial steps: an empty ASP.NET web application

You can of course just open Visual Studio 2013/2015 and start a new Web API project and you would be done:

Instead, we’ll start from an empty project instead and add in the necessary OWIN elements one by one.

I’m basing this series on Visual Studio 2013. I’m not sure how different it will be in VS 2015 but I hope these steps won’t be awfully outdated soon. So open VS 2013 and create a new ASP.NET Web Application called CustomersApi:

On the next screen select the Empty project type:

You’ll be given an empty project as promised:

You’ll notice that the System.Web dependency has been added to the project by default:

If you further check the list of referenced libraries you won’t see anything related to OWIN yet. That’s an important characteristic of OWIN/Katana that you can add only the required Katana components, called middleware to your project. You may not need everything from System.Web in which case it’s too large a dependency to carry along. You’ll definitely need it for IIS deployment but not if your Web API project is deployed on another platform.

Adding some components

Let’s first add the Web API core library from NuGet to the project:

This will install a couple of other dependencies like Newtonsoft or System.Net.

Next add a folder called Controllers to the project. Right-click the Controllers folder and select Add, Controller:

In the Add Scaffold window select Web API 2 Controller – Empty:

In the Add Controller window provide “CustomersController” as the name of the controller. You’ll be given an empty Web API controller that derives from ApiController:

namespace CustomersApi.Controllers
{
    public class CustomersController : ApiController
    {
    }
}

Add another folder to the project called Model and a class called Customer into it:

public class Customer
{
	public string Name { get; set; }
	public string Address { get; set; }
	public string Telephone { get; set; }
}

Back in CustomersController let’s add a Get method that will return all the customers:

public class CustomersController : ApiController
{
	public IHttpActionResult Get()
	{
		IList<Customer> customers = new List<Customer>();
		customers.Add(new Customer() { Name = "Nice customer", Address = "USA", Telephone = "123345456" });
		customers.Add(new Customer() { Name = "Good customer", Address = "UK", Telephone = "9878757654" });
		customers.Add(new Customer() { Name = "Awesome customer", Address = "France", Telephone = "34546456" });
		return Ok<IList<Customer>>(customers);
	}
}

We now want to set up the routing so that the /customers endpoint is directed to the CustomersController and its Get action. We’ll do that through OWIN components. We’ll be adding OWIN middleware through these Katana components that can gradually add more and more steps in your application pipeline.

If you’ve done any NodeJs development then these chained elements will look familiar. In NodeJs the elements are linked by way of callbacks. If you’re interested in learning NodeJs you can start with this post on this blog.

In order to integrate the OWIN pipeline into our application we’ll need to add a couple more NuGet packages. First off the OWIN version of System.Web:

Second let’s add the following NuGet package:

The Startup class

The Startup class is the entry point into a Katana-based application. It’s like Global.asax in a traditional ASP.NET app. If you go through the posts on OWIN/Katana referenced above you’ll know that by convention this entry point class must be called “Startup” and not “StartUp” or “startup” i.e. the casing is important. Another convention is that the Startup class must contain a method called Configuration which accepts an object of type IAppBuilder.

Therefore add a class called Startup to the root of the project:

public class Startup
{
	public void Configuration(IAppBuilder appBuilder)
	{

	}
}

This is where you can wire up your application. We’ll start by adding the necessary routing table. Add another class called WebApiConfig to the class with the following content:

public class WebApiConfig
{
	public static void Register(HttpConfiguration config)
	{
		config.Routes.MapHttpRoute(
			name: "AllCustomers",
			routeTemplate: "customers",
			defaults: new { controller = "Customers", action = "Get"}
			);
	}
}

If you’ve done any MVC .NET development then this should be easy to follow. We simply route the /customers endpoint to the Customers controller and the Get action. It’s not necessary to be this explicit as we follow the MVC conventions but there you go.

We can now fill in the Configuration method as follows:

public void Configuration(IAppBuilder appBuilder)
{
	HttpConfiguration httpConfiguration = new HttpConfiguration();
	WebApiConfig.Register(httpConfiguration);
	appBuilder.UseWebApi(httpConfiguration);
}

UseWebApi is an extension method of IAppBuilder where you can pass in the configuration object.

We’re ready to go. Press F5 to run the application and navigate to /customers in the browser, e.g. http://localhost:50061/customers

How the customer objects are presented depends on the browser type but in Chrome it looks like this:

In the next part we’ll look at OWIN hosting.

View the list of MVC and Web API related posts here.