Ajax is a the name for a set of technologies that, in various forms (and with different appellations), has been around since 1997. Ajax became a de facto standard for websites around 2007, and it contributed significantly to changing the perspective of Web development. However, it is not far-fetched to state that Ajax has been the poisoned arrow in the heel of ASP.NET Web Forms.

The growing adoption of Ajax mined the foundation of ASP.NET Web Forms — hiding the underlying HTML and JavaScript from server-side developers. Microsoft has been quick with updates to the ASP.NET Web Forms API to give developers more and more control over the emitted HTML and JavaScript, and this made it possible for all sites based on Web Forms to incorporate some Ajax capabilities.

In the context of a website, Ajax capabilities essentially mean the ability to download data from HTTP endpoints for the most-part hosted on the same domain as the site. Such HTTP endpoints are expected to serve plain data instead of HTML markup, so that client-side code can update the page in a much smoother way. For ASP.NET developers, there's been just one way of implementing these necessary HTTP endpoints — using one of the flavors of the Windows Communication Foundation (WCF) API.

The Overkill Instinct of WCF

WCF was originally designed to support SOAP and WS-* standards over a wide variety of transportation protocols. More importantly, WCF was devised to be totally independent from the transportation protocol, whether HTTP, TCP, FTP, MSMQ, or others. But it soon became clear that WCF had to be revisited to provide quality support for non-SOAP services, and specifically, it needed to serve efficiently plain XML, text, and JSON over HTTP.

Over the years, developers relied on various extensions to WCF, such as the webHttpBinding protocol and the REST starter kit. None of them really warmed developers' hearts though. While WCF generally worked well over HTTP, some structural aspects were viewed as cumbersome. It's hard to deny that WCF tends to overuse attributes and configuration. In addition, WCF was not well designed for testability.

And while Web Forms developers were experiencing difficulties using WCF for implementing HTTP endpoints, ASP.NET MVC was providing a much more seamless experience to developers enabling them to always use controllers to return both markup and JSON or XML.

An Attempt to Unify the Web APIs

While WCF remains the foundation for interoperable applications, developers often need to remove the heavy machinery of WCF to deal with common simple scenarios, which require only a thin, HTTP-focused framework. Essentially, all that developers usually need is a basic framework to build endpoints to receive and upload JSON data via HTTP.

.NET Framework 4.5 comes with a new API that incorporates most of the good aspects of ASP.NET MVC controllers, but lives outside of ASP.NET MVC. This new API is called the "Web API" and is available only in .NET 4.5 applications. You can use the Web API from both ASP.NET MVC and ASP.NET Web Forms and, more importantly, the programming patterns are just the same.

To an external observer, the Web API looks mostly like a duplicate of the ASP.NET MVC controller. Indeed, overlapping between ASP.NET MVC controllers and Web API components does exist. However, you should really view the Web API as an attempt to unify all existing practices for building HTTP services for ASP.NET under a single programming pattern.

Inside the Web API

The Web API is based on controller classes. Web API controllers are similar (but not identical) to ASP.NET MVC controllers. From a developer's perspective, all that is required is the creation of a plain C# (or Visual Basic) class inherited from ApiController. This controller class is expected to expose public methods that accept any sort of arguments and return any sort of serializable data types.

In an ASP.NET Web Forms application, you just add a class to the project and write the public methods you want to be able to call back from client Web pages. Most of the time, you won't even care about formatting the output to JSON. If a method is conceptually expected to return an array of Customer objects, you just return that array from your method. Web API comes with an underlying framework that takes care of a number of things with a convention-over-configuration kind of approach that has both pros and cons. The following code snippet offers a glimpse of the basic Web API controller:

public class CustomerController : ApiController
{
   public IEnumerable<Customer> Get() {
      return new Customer[] { new Customer(1), new Customer(2) };
   }
   public void Post(Customer customer)
   { ... }
   public void Put(int id, Customer value)
   { ... }
}

The Web API framework assumes you want to build a REST-based API for some kind of data object — for example, a Customer. You have methods that follow the REST approach and give parameters of the specified type — Put, Delete, Post, and Get. The underlying framework maps the detected HTTP verb to any public method whose name begins with a matching substring, such as PutXxx, DeleteXxx, and the like. The returned value is automatically serialized to JSON unless a different format is expressly requested through the Accept HTTP header.

If you want to shape the public API in a way that does not use REST, then you must resort to attributes and a programming style that is similar to standard ASP.NET MVC controllers. Either way, the new Web API is a welcome addition — providing a testable and unified API, and a way to build HTTP services that are not tied to IIS, but can be hosted everywhere.

Dino Esposito frequently writes on Microsoft technology topics.