The Tale of the ASP.NET Web API

As most of you probably know, with the drop of the of the MVC 4 Framework Microsoft introduced us to a shiny new framework called the ASP.NET Web API. Anytime new frameworks come out open source or otherwise, you have to ask yourself a few important questions.

What?

The first and most obvious question we need to ask is “What the heck is this new framework?”.  In the case of the ASP.NET Web API this is a pretty simple question to answer. The ASP.NET Web API is now the recommended approach for developing HTTP based services and REST based services in the .NET stack. See it’s simple!

Why?

Secondly, and more importantly, is the question “Why did the create this framework?”. After all, we have WCF; we have MVC; so why introduce another framework into an area that is already a bit confusing?

An Illustration of Pain

To help illustrate why this framework was introduced, I would like you to look at a few images. While looking at them ask yourself a question. Why are these people feeling so much pain? What is it that is making them look miserable?

Our Distressed Woman

Frustration

Anger

 

So what is going on here? What is it that’s making these folks so angry? As I look at these pictures, this is the story that plays out in my mind.

The Story

This is a group of .NET developers, who for the last three years have been working on a suite of REST based services, but because of the corporate standards of the company they work for they have been forced to do this using WCF. So for the greater part of three to four years, these people have been fighting against a technology that was not necessarily designed to solve the problems they were facing.

HTTP + WCF = 😦

Now I don’t mean any disrespect to WCF. But the truth is that from its inception and from the ground up, WCF was designed with SOAP based web services in mind. It was developed to be highly scalable, highly pluggable, highly configurable as well as any other ‘able’ you can think of. It was also designed to work across multiple transport protocols be it TCP/IP, Named Pipes and most recently even HTTP. All this is extremely powerful stuff  if it is what you want. However,  if what you need is a simple HTTP service to send data to, or to obtain data from, the WCF development experience starts to feel heavy, its hard, its complicated and honestly just not much fun. Thankfully, Microsoft acknowledged this, and as HTTP services became more prevalent they took steps to make things easier on us.

The WebHttpBinding

Enter .NET 3.5 and the introduction of the WebHttpBinding. For the first time,  WCF developers could now expose their WCF services as HTTP end points. A step in the right direction? Absolutely.  However, it did not quite go far enough. Relegating HTTP to more of a transport protocol as apposed to application protocol the WebHttpBinding was more a way to transfer data from one server to another then it was anything else. But the HTTP semantic is much richer than just a transport protocol.  We have things like caching, etags, and many other things that have become more and more important as HTTP services have taken over the service landscape. And its these things that HTTP service developers need to be able to target when building their services. So was the WebHttpBinding  a step in the right direction? Yes. But unfortunately for us it did not go far enough.

The Rest Starter Kit

Next we got something called the Rest Starter Kit. I never actually got to work with this;  however, I have read that it was actually well received by many. However as it is with many things from Microsoft the Rest Starter Kit never made it past the community preview, and as such is just a blip in the .NET history book.

The WCF Web API

The WCF Web API, the third and final attempt to build on top of WCF strong support for HTTP based services. In all fairness to the WCF team,  this was a giant leap in the right direction. We started to see a convention a based approach opposed to the massive WCF configuration files. We were given a nice client to interact with our services, and we even started to see the support for content negotiation. However, this all fell into a category of a too little and too late. .NET developers frustrated with the lack of support for HTTP based services and with open source solutions available, things like OpenRasta, and Service Stack, .NET developers had moved on. Some of the savvier .NET folks even started to build their HTTP services on top of MVC, and even this approach proved to be more straight forward than using the latest WCF Web API.

What To Do

At this point,  Microsoft found themselves in a bit of a precarious position, and they had to make a choice. Do they continue to push WCF into a box it was never intended to fit into or do they stop, look around at the community, and create something directly targeted at the problem of HTTP based services and REST based services. Thankfully for us they chose the latter. And with the release of Visual Studio 2012 and MVC 4 we were given the brand new shiny ASP.NET Web API.

Taking the good from the WCF Web API, and what they have learned form the MVC stack. They created a new framework that brings a slew of desirable features.

Modern

A much more modern HTTP programming model. Largely convention based, Asynchronous from top to bottom, we have a really nice HttpClient to interact with our services, and quite frankly it just a lot of fun to work with.

MVC

Because the ASP.NET Web API is based on top of the MVC framework we get a lot of the magic that exists in the MVC stack. Things like routing, action filters, model validation and of course the added benefit of the development experience feeling very much at home if you are already a MVC developer.

Content Negotiation

As service developers,  we need to be cognisant of the types of data our clients want to work with. Maybe they want XML maybe they want JSON out of the box the ASP.NET Web API supports both. And of course the extensions points are there if you want to create your custom media type, or use something RSS or ATOM.

OData

If you want to expose your HTTP service to URI based queries, there is OData support for that, and it gets better all the time with the ongoing nightly builds.

Testable

And last but not least the framework is testable. If any of you remember how hard it is to unit test, and integration test WCF services, you will understand why this is such a beautiful thing. Built with testability in mind from top to bottom it is one of the most testable frameworks in all of the .NET stack.

Why HTTP?

The last thing I want to address is a question I was first asked when I presented this topic at MDC last year. Someone in the audience asked ‘Why so much emphasis on HTTP, is there something wrong with SOAP based services?’

The answer to that question is simple. There is nothing wrong with SOAP based services. However, in the gadget landscape of today, many devices know how to work with HTTP natively. Far less understand the different abstractions that sit on top HTTP, such as SOAP. So it should not surprise anyone  that HTTP based services are the new standard.

Does this mean SOAP and WCF are dead? No, not at all. WCF and SOAP just solve different problems. If you need to work with multiple transport protocols, or if you need WS-* style security WCF is still the king. Where the ASP.NET Web API shines, is in the space of HTTP. So in short, each solves a different problem, and each solves does it exceptionally well.

-BDN