WCF or ASP.NET Web APIs? My two cents on the subject

A couple of weeks ago (around Feb. 16) the WCF WebAPIs - a framework for building RESTful/Hypermedia/HTTP services, which was in development over the past 1.5 years as a side-project on CodePlex, has been formally integrated into ASP.NET and its name changed to the ASP.NET Web API.

These past two weeks, there has been a lot of questions among WCF developers: What does it mean that the Web APIs are no longer a part of WCF – is WCF dead? Has SOAP gone bankrupted? is HTTP the new way to go for interoperability?

To get a better understanding of what happened and what is the way to go, we need to answer a couple of questions:

1. What is the purpose of the WebAPIs?

2. Why do we need REST HTTP services? What’s wrong with SOAP-over-HTTP?

3. Why did the WebAPIs move from WCF to ASP.NET MVC?

4. Is there still a use for WCF? When should I choose Web APIs over WCF?

What is the purpose of the WebAPIs?

When WCF was conceived back in its Indigo and .NET 3 days, the main goal was to support SOAP + WS-* over a wide variety of transports. However, over time it became clear that although SOAP is wide spread and supported on many platforms, it is not the only way to go when creating services. There is also a need to also support non-SOAP services, especially over HTTP, where you can harness the power of the HTTP protocol to create HTTP services: services that are activated by simple GET requests, or by passing plain XML over POST, and respond with non-SOAP content such as plain XML, a JSON string, or any other content that can be used by the consumer. Support for non-SOAP services was very much needed in WCF back then, mostly because some clients, such as web browsers, were not that suitable to handle SOAP messages (plenty of XML parsing and DOM manipulation).

So in WCF 3.5 we got the WebHttpBinding – a new binding that helped us create this kind of non-SOAP service over HTTP, better known as a RESTful service.

The WebHttpBinding was not enough, and after WCF 3.5 was released, a new set of tools was created – the WCF REST Starter Kit. The REST starter kit was an attempt to enrich the support of WCF 3.5 for HTTP services – add better client-side support for .NET apps, extend the server side support for other content types, enable response and request caching, inspection of messages and so forth. Unfortunately, this great toolkit was never officially released and ended its product cycle as “Preview 2”, although it’s still being used today in some of Microsoft’s products that are built with .NET 3.5.

Although not released, some of the service-side features of the REST starter kit were integrated into WCF 4 – we didn’t get any of the client-side libraries, but we did get most of the service-side features (excluding the new inspectors). Some were well-integrated into WCF while others required the use of ASP.NET (by turning on the ASP.NET compatibility mode).

So with WCF 4 we had some support for “Web” HTTP services, but it wasn’t that perfect – to get some of the features you needed IIS hosting and ASP.NET, not all types of requests were supported easily (ever tried posting HTML form data to a WCF HTTP service?), the overuse of CLR attributes to define the POST/GET/PUT/DELETE was tedious, not to mention the configuration required to create this type of services with all of the endpoint behavior. And even after all of that we didn’t actually get full control over the HTTP messages.

That was the main goal of the Web APIs, known back then as the WCF Web APIs: to stop looking at HTTP through the eyes of WCF - as just a transport protocol to pass requests. Rather, it allows us to look at it as the real application-level protocol it is – a rich, interoperable, resource-oriented protocol. The purpose of the Web APIs was to properly use URIs, HTTP headers, and body to create HTTP services for the web, and for everyone else that wished to embrace HTTP as its protocol and lifelong friend.

Why do we need REST HTTP services? What’s wrong with SOAP-over-HTTP?

The world of SOAP and the world of HTTP services are very different. SOAP allows us to place all the knowledge required by our service in the message itself, disregarding its transport protocol, whether it is TCP, HTTP, UDP, PGM, Named Pipes… But unlike TCP, UDP and the other level 4-5 protocols, HTTP is an application-level protocol, and as such it offers a wide variety of features:

• It supports verbs that define the action - query information using GET, place new information and update existing using POST or PUT, remove information using DELETE etc.
• It contains message headers that are very meaningful and descriptive - headers that suggest the content type of the message’s body, headers that explain how to cache information, how to secure it etc.
• It contains a body that can be used for any type of content, not just XML content as SOAP enforces (and if you want something else – encode it to base64 strings and place it in the SOAP’s XML content). The body of HTTP messages can be anything you want – HTML, plain XML, JSON, binary files (images, videos, documents…) …
• It uses URIs for identifying both information paths (resources) and actions – the URI templates initiative is catching on and is rapidly becoming the standard way of representing requests for resources and hypermedia URIs.

The use of HTTP has evolved over the years. Application-level protocol architectural styles such as REST Hypermedia APIs have emerged on top of HTTP. These, in turn, harness the power of HTTP to create resource-oriented services, and better define the stateless interaction between clients and services.

The Web APIs therefore were intended to allow all of these approaches – you can use it to create HTTP services that only use the standard HTTP concepts (URIs and verbs), and to to create services that use more advanced HTTP features – request/response headers, hypermedia concepts etc.

So HTTP is a lot more than a transport protocol. It is an application-level protocol, and the fact is that although many platforms know how to use SOAP, many more platforms know how to use HTTP! among the HTTP supporting platforms which do not support SOAP that well are the browsers – probably the most important platforms for web developers (and users). And if you don’t believe me that REST and hypermedia are useful, maybe Martin Fowler can convince you better than me.

This, of course, does not mean that SOAP is redundant – SOAP is still useful for building messages when you don’t have an alternative application-level protocol at your disposal, or when you want to use SOAP across the board while considering HTTP as no more than another way to pass messages (for example, use HTTP because it can cross firewalls more easily than TCP).

Why did the WebAPIs move from WCF to ASP.NET MVC?

Back to the story of WCF and the WCF Web APIs (we are still before the merger). Another goal of the WCF Web APIs was to incorporate known concepts that would help developers to overcome some of the drawbacks they faced with WCF, such as huge configurations, overuse of attributes, and the WCF infrastructure that did not support testing well. Thus the Web APIs used IoC, enabled convention-over-configuration, and tried to offer simpler configuration environment.

The problem was that at that point in time there were several approaches for constructing HTTP services:

1. WCF with the WebHttp binding and REST support.

2. The new WCF Web APIs, soon to be ASP.NET Web APIs.

3. A not-so-new framework, ASP.NET MVC, which took a break from being HTML-oriented (getting requests from HTML pages and returning HTML/JSON) to being Resource-oriented – people started realizing that they can consider controllers as services and use the MVC infrastructure to define the control requests, responses, and better control the HTTP message.

4. Open source frameworks such as OpenRasta and ServiceStack.

In addition to that, as time passed, the WCF Web APIs had a lot of trouble adapting WCF to the “native” HTTP world. As WCF was primarily designed for SOAP-based XML messages, and the “open-heart” surgery that was required to make the Web API work as part of WCF was a bit too much (or so I understand from people who were involved in creating the Web APIs). On the other hand, the ASP.NET MVC infrastructure with its elegant handling of HTTP requests and responses, and its support of easy-to-create controllers seemed like the proper way to go for creating this new type of services.

So the fact was we had too many options and therefore too much confusion. What were we to do? We merge teams! (Kind of reminds us of the time of LINQ-to-SQL and Entity Framework, WCF and Ado.Net Data Services and other such examples). So the WCF team and the ASP.NET team joined forces and created a new framework focused on the world of REST/Hypermedia/HTTP services for the web world and thus came out the ASP.NET Web APIs.

I’m still not so sure about the choice of names, as the new Web APIs can also work outside of ASP.NET with the use of WCF, but I guess that the name “WCF ASP.NET Web API” was a bit long. Maybe “WASP Web API”? “WAWAPI” (Wcf Aspnet Web API)? Or maybe simply call it “Hypermedia Web API”?

So this merger is intended to reduce confusion, not induce it. I guess that if it was explained at that time, it might have caused less confusion over time (see the Silverlight is dead slip of PDC 2010). Does Microsoft need a new DevDiv PR team?

Is there still use for WCF? when should I choose Web APIs over WCF?

Recall my points from before - HTTP is a lot more than a transport protocol; use SOAP across the board and consider HTTP as no more than another way to pass messages.

• If your intention is to create services that support special scenarios – one way messaging, message queues, duplex communication etc, then you’re better of picking WCF
• If you want to create services that can use fast transport channels when available, such as TCP, Named Pipes, or maybe even UDP (in WCF 4.5), and you also want to support HTTP when all other transports are unavailable, then you’re better off with WCF and using both SOAP-based bindings and the WebHttp binding.
• If you want to create resource-oriented services over HTTP that can use the full features of HTTP – define cache control for browsers, versioning and concurrency using ETags, pass various content types such as images, documents, HTML pages etc., use URI templates to include Task URIs in your responses, then the new Web APIs are the best choice for you.
• If you want to create a multi-target service that can be used as both resource-oriented service over HTTP and as RPC-style SOAP service over TCP – talk to me first, so I’ll give you some pointers.

I hope this helped you removing some of the confusion over this topic.

CodeProject