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:

Create new Web Api project in Visual Studio

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:

Create new ASP.NET project in Visual Studio

On the next screen select the Empty project type:

Craete empty project

You’ll be given an empty project as promised:

Starting point of empty asp.net project

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

System.Web dependency added to empty project by defaul

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:

Install Web API 2 core library from Nuget

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:

Select add controller from context menu in visual studio

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

Add empty Web API controller

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:

Install SystemWeb OWIN through NuGet

Second let’s add the following NuGet package:

Install Web API Owin through NuGet

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:

Customers list presented as XML

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

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

Advertisements

About Andras Nemes
I'm a .NET/Java developer living and working in Stockholm, Sweden.

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

  1. Majid says:

    Thank you dear Anderas. The post was very helpfull.

  2. maruthi says:

    Detailed Article. Thank you.

  3. Nice example, Andras. Visual Studio 2015 U3 was released last month and I tried to register my web api but found that the IApplicationBuilder (was IAppBuilder in RC2) did not contain a definition for the UseWebApi extension method. Any ideas please?

  4. Dave Smith says:

    Extremely helpful post, Andras. Thank you very much.

  5. Perfect article!
    But sorry, I was gone wrong direction because of your typing mistake.

    “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:”

    It should be “First of the OWIN version of System.Web:”.

    Silly mistake but really confusing for beginners. Sorry again to complain.

  6. Robert says:

    Thanks Andras! I also prefer to use web services. So learning about this light weight alternative OWIN was a great help. Your walkthrough was just what I was searching for.

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

ultimatemindsettoday

A great WordPress.com site

iReadable { }

.NET Tips & Tricks

Robin Sedlaczek's Blog

Developer on Microsoft Technologies

HarsH ReaLiTy

A Good Blog is Hard to Find

Ricos Blog zu Softwaredesign- und architektur

Ideen und Gedanken rund um Softwaredesign und -architektur, Domain-Driven Design, C# und Windows Azure

the software architecture

thoughts, ideas, diagrams,enterprise code, design pattern , solution designs

Technology Talks

on Microsoft technologies, Web, Android and others

Software Engineering

Web development

Disparate Opinions

Various tidbits

chsakell's Blog

Anything around ASP.NET MVC,WEB API, WCF, Entity Framework & AngularJS

Cyber Matters

Bite-size insight on Cyber Security for the not too technical.

Guru N Guns's

OneSolution To dOTnET.

Johnny Zraiby

Measuring programming progress by lines of code is like measuring aircraft building progress by weight.

%d bloggers like this: