The Basics

ASP.NET Web API is a web framework that is built on top of Microsoft .NET 4.0 and above, implements the HTTP (HyperText Transfer Protocol) specification, and can be used to build or consume HTTP service, as opposed to SOAP (Simple Object Application Protocol) or WCF (Windows Communication Foundation) services. As we will see later, ASP.NET Web API started its life as WCF Web API, but as the team started building the framework, it became more and more evident that it was best suited as a web framework rather than a service framework. As such, the team became part of the ASP.NET team and started working with them to build the rest.

The first version of the project was released in August 2012 along with Visual Studio 2012, .NET 4.5, and ASP.NET MVC (Model-View-Controller). The next version of the framework is due to be released in late 2013.

As Glenn Block, one of the key ASP.NET Web API project leaders puts it, ASP.NET Web API embraces HTTP as a first-class citizen and makes it extremely easy to build RESTful services. So ASP.NET Web API implements RFC 2616 (HTTP 1.1 specification) while staying nonopinionated toward REST. (REST or REpresentational State Transfer is covered as part of Chapter 3.) This was a key decision by the team, which kept ASP.NET Web API from getting entangled in the endless controversies surrounding REST and enabled it to stay practical, pragmatic, and focused on delivering value through implementing HTTP. As such, in the rest of this book we usually avoid the common phrase REST API (unless we actually mean RESTful) and instead use the phrase HTTP API.

ASP.NET Web API can be used to turn a traditional ASP.NET web project into a powerful HTTP API capable of taking advantage of all the richness of HTTP including content negotiation, caching, concurrency validation, and so forth. The client part of the framework can be used by desktop or Windows phone applications (as well as server applications and middleware) to consume any HTTP API written in any framework as long as it stays compliant with the HTTP specification.

ASP.NET Web API is revolutionary in many aspects not limited to the promise it delivers. It was one of the first Microsoft projects to run completely as an open source project that accepts contributions and fixes from the community. It has fully engaged with the community, constantly receiving feedback, and the team has been listening carefully to what the community has been saying.

ASP.NET Web API was inspired by the ASP.NET MVC concepts and design, and it was built with similar abstractions. If you are familiar with ASP.NET MVC, you will see many parallel implementations (such as controllers, actions, filters, etc.). Yet as you will see, it improved on the modularity of its components and is an independent implementation from ASP.NET MVC and can be used on its own.

ASP.NET Web API Libraries

ASP.NET Web API can be downloaded or used as NuGet packages. Also in order to get Visual Studio project templates, you need to download and install ASP.NET MVC 4.

To download ASP.NET MVC 4, you can go straight to the Microsoft Download Center and look for the ASP.NET MVC 4 bundle, or you can use the Web Platform Installer and choose ASP.NET MVC 4, which will contain the essential libraries for building ASP.NET Web API as well as Web API project templates as part of the ASP.NET MVC 4 templates.

If you would like to add NuGet reference to your project, depending on your scenario, you need to select from the different NuGet packages available. Each of these NuGet packages contains a subset of the framework tailored for a particular use case. It is important to note that some of these libraries are additions to the .NET Framework and are now standard DLLs (Dynamic Link Library) of .NET 4.5. Table 1-1 lists the ASP.NET Web API NuGet packages and their use cases.

One of the interesting aspects of ASP.NET Web API is that Microsoft decided to have a dependency on Newtonsoft.Json, which is an open source library. Although this had happened before with jQuery in previous versions of MVC, this is the first time Microsoft has had an open source .NET library dependency. Newtonsoft.Json is an excellent JSON (JavaScript Object Notation) implementation widely adopted in the community.

Because work on the ASP.NET Web API is ongoing, there are also prerelease NuGet packages available for some of the libraries listed above.

ASP.NET Web API Source Code

As part of the Microsoft initiative to embrace open source software (OSS), ASP.NET Web API (along with some other projects such as Entity Framework 5.0) started its life as an open source project. The project was (and is) hosted on the CodePlex web site as a Git repository and run under agile methodology with the complete visibility of the whole backlog. You can download the source code from http://aspnetwebstack.codeplex.com/SourceControl/latest. Alternatively, you can clone the Git repository hosted on the CodePlex web site. Complete instructions on how to set up Git and then clone the repository can also be found on the CodePlex web site (http://aspnetwebstack.codeplex.com/).

After downloading the source code, you can run the build.cmd file in the command prompt. Before doing that, you might have to open the solution and enable the NuGet package restore on the solution so the NuGet dependencies can be downloaded. We highly recommend to download the source code, review the code, and get a feel for the extent of the framework.

You can also download the nightly build libraries containing prerelease features of the ASP.NET Web API from the same web site.

HTTP

In the early 1990s, a few talented engineers in the CERN laboratory, led by Tim Berners-Lee, were working on a concept called the World Wide Web (originally one word, “WorldWideWeb”), which was meant to provide document exchange over the network. World Wide Web, also known as WWW or W3,was initially targeted at scientific organizations over the world to be able to author, publish, and exchange research materials. By the end of 1990, Tim Berners-Lee already had a working prototype of a web server and a browser capable of rendering documents and traversing links.

In 1993, CERN decided that WWW would no longer be a proprietary body of work and it would be free for everyone to use. This led the way for an international body created by the end of 1994, which was known as the World Wide Web Consortium or W3C.

W3C started to formalize the work that had been done in CERN, and as a result, drafts of a few key protocols were created. These protocols were later known as HTTP, HTML, and URI based on the earlier work by Tim Berners-Lee. These three protocols were the building blocks of the revolutionary phenomenon that we know now as the Internet. A timeline of these events is provided in Table 1-2.

W3C published the HTTP 1.0 specification in 1996 as part of RFC 1945. This specification listed three authors: Tim Berners-Lee, Roy Fielding, and Henrik Frystyk Nielsen. By the time HTTP 1.1 was published in 1999 by the same authors (and a couple more), HTTP was not merely a document exchange protocol, it was the engine of distributed computing for many years to come.

Roy Fielding, best known for proposing the REST architectural style, was seminal in bringing distributed computing concepts such as caching and concurrency to the heart of HTTP. At the time of writing HTTP 1.1 spec, he was studying toward his PhD in information and computer science, and as part of his thesis, he was working on an optimal architectural style for distributed computing. Chapter 5 of his dissertation is on REST, which was later popularized (and even idolized) by the community in the latter half of 2000. We will discuss and review REST in Chapter 3, but here it is important to note that a lot of REST is already considered (or even fulfilled) part of HTTP 1.1.

POST /api/v1/person HTTP/1.1
host: example.com
Content-Type: x-www-form-urlencoded

name=joe&surname=blogg

201 Created
Content-Type: text/plain
Location: /api/v1/person/123

Person was successfully created

Henrik Frystyk Nielsen was also a key part of the WWW success as he was working with Tim Berners-Lee in the early years of CERN and is a contributor to both HTTP 1.0 and 1.1 specifications. It is very interesting to know that Henrik is actually the architect of the ASP.NET Web API project and has ensured that all the goodness of the RFC 2616 is exposed in this project. After publication of HTTP 1.1, he joined Microsoft to work on a new protocol named SOAP, which ironically delayed the adoption of HTTP as the programming model of the distributed computing.

SOAP

SOAP was proposed by Dave Winer and Don Box in 1998. SOAP was designed to solve the problem of hybrid platform enterprises where each system used a proprietary means of communication and was unable to connect to other systems. SOAP proposed the use of HTTP as the transport mechanism for sending and receiving XML (Extensive Markup Language) data. At that time, XML was seen as the text-based data language that would “save the world,” so it was inevitable that XML and web (HTTP) should be combined to form a protocol.

In 1998, creating objects in many programming languages was deemed expensive. As such, many technologies such as COM/DCOM (Distributed Component Object Model) and CORBA (Common Object Request Broker Architecture) had been created to share the business logic through the objects hosted on a central server. Microsoft was working on Microsoft Transaction Server (MTS), which later turned into COM+, which was designed to create and pool business objects on a server that could be accessed by various clients. This is being mentioned because the naming of SOAP probably had a lot to do with the time and company context in which SOAP was formed. As later was experienced, SOAP did not have a lot to do with accessing objects because the underlying systems were being abstracted behind a contract. Also, as many learned, it was not necessarily simple either, especially with the WS-* extensions, as we will see.

The SOAP programming model embodies the Remote Procedure Call (RPC) paradigm where a client does what can be modeled as calling a method or procedure on the remote system by sending input parameters and receiving the return parameter over the network. This RPC paradigm was already implemented in DCOM and CORBA, but they were not compatible. SOAP was solving the cross-platform communication problem by using a widely adopted high-level transfer protocol (HTTP), which was built on top of TCP/IP (Transmission Control Protocol/Internet Protocol) and used a text-based messaging format (XML), which was very promising. HTTP is normally served over port 80, which is usually an open port. On the other hand, all systems were capable of processing text, hence processing XML was not a technical challenge in itself.

SOAP was used to build web services connecting different platforms and systems. It brought the opportunity to build real B2B (business-to-business) systems, allowing companies to generate more revenue through more reach and broader wholesale markets. On the other hand, SOAP was the enabler to build web services to implement Service-Oriented Architecture (SOA), where each service exposes its boundary.

Different software and platform vendors jumped on the SOAP bandwagon and soon built the necessary software development kit (SDK) for building and running SOAP web services. Microsoft introduced ASP.NET Web services (sometimes also referred to as ASMX Web services because file extensions ended in .asmx rather than .aspx), and it was relatively easy to add web services to an existing ASP.NET application.

The contract definition for web services was formalized as Web Service Definition Language (WSDL), which used XML schema for defining the input and output schemas. WSDL allowed client proxy generation to be automated, helping developers to quickly build an application capable of consuming a web service.

The world was good again, until it was not.

Web Services Extensions

Web services lacked many aspects required by scalable distributed computing. The design of SOAP was rushed due to the pressure caused by its own buzz, which led to inconsistent versions 1.1 and 1.2 being adopted by some yet rejected by others, which made cross-platform communication (which was the promise of the SOAP) more challenging.

One of the aspects seriously neglected in all of this was security. In 2004, an effort was made by the Organization for the Advancement of Structured Information Standards (OASIS) to formalize a protocol to secure web service communication by the means of username/password tokens. This protocol was later known as WS-I Basic Profile 1.0, and it became a very popular implementation among enterprises. Listing 1-1 shows an example of the protocol.

Listing 1-1.  A Sample WS-I Basic Profile SOAP Security Header

<wsse:Security xmlns:wsse=' http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd '
               xmlns:wsu=' http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
               utility-1.0.xsd'
               xmlns:xenc=' http://www.w3.org/2001/04/xmlenc# '
               xmlns:ds=' http://www.w3.org/2000/09/xmldsig# ' >
   <wsse:BinarySecurityToken wsu:Id='SomeCert'
                             ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
                             x509-token-profile-1.0#X509v3"
                             EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
                             wss-soap-message-security-1.0#Base64Binary">
lui+Jy4WYKGJW5xM3aHnLxOpGVIpzSg4V486hHFe7sHET/uxxVBovT7JV1A2RnWSWkXm9jAEdsm/hs+f3NwvK23bh46mNmnCQVsUYHbYAREZpykrd/+ByeFhmSviW77n6yTcI7XU7xZT54S9hTSyBLN2Sce1dEQpQXh5ssZK9aZTMrsFT1NBvNHC3Qq7w0Otr5V4axH3MXffsuI9WzxPCfHdalN4rLRfNY318pc6bn00zAMw0omUWwBEJZxxBGGUc9QY3VjwNALgGDaEAT7gpURkCI85HjdnSA5SM4cY7jAsYX/CIpEkRJcBULlTEFrBZIBYDPzRWlSdsJRJngF7yCoGWJ+/HYOyP8P4OM59FDi0kM8GwOE0WgYrJHH92qaVhoiPTLi7
   </wsse:BinarySecurityToken>
</wsse:Security>

(Taken from the specification atwww.ws-i.org/profiles/basicsecurityprofile-1.0-2004-05-12.html.)

Around this time, a body of work was initiated by working groups and contributed to by the big software vendors (such as Microsoft, Oracle, IBM, etc.) to create extensions to the web services (or rather SOAP). These were known as WS-*, and this led to a very diverse set of specifications, some of which never saw the light of day. During rapid turnaround of the draft specifications, vendors were publishing frameworks only to be broken by the next update. Microsoft Web Services Extension (WSE) had up to three different versions, each with several service packs. For example, Basic Profile 1.0 was first implemented in WSE 2.0 SP3.

The work on these drafts continued, but as we will see, by the time they were finalized, they were so complex no one could understand or implement them. Web services extensions meant to enhance SOAP, but as we will see later, instead they seemed to kill it.

WCF

WCF (codenamed Indigo) was one of the three “foundations” released as part of .NET 3.0. The others were Windows Presentation Foundation (WPF) and Windows Workflow Foundation (WF), with the latter having a lackluster start and, at the time of this writing, is still being redesigned.

WCF was a bold and ambitious move to abstract RPC once and for all. It took the SOAP schema as its internal implementation but completely abstracted the transport so that, unlike SOAP, it was not tied to HTTP. It was designed to be able to use TCP, named pipes, and even asynchronous MSMQ (Microsoft Message Queuing) as well as HTTP, and in terms of WS-*, it supported many of the new and shiny protocols coming out of the WS-* factory (such as wsHttpBinding and wsFederationHttpBinding). It used the pipe and filter pattern to implement a message processing pipeline in both the client and server. These pipes and filters sequentially process the message with respect to encoding, transport, security, reliable messaging, and transactions. WCF also had many extensibility and aspect-oriented points at which one could step in and customize the implementation. The classic SOAP web service was also supported, as it became just one binding out of a dozen (basicHttpBinding). It came with error logging, tracing, debugging, and diagnostics tools and functionalities built in to the framework. It could be hosted on an Internet Information Server (IIS), a Windows service, or any plain old .exe process (such as Windows Forms, WPF, or a console app) and could be consumed equally by servers, ASP.NET Web applications, and desktop applications.

But there were problems. First, abstracting the transport means that only the least common denominator of the transport features will be available. Considering such a diverse range of transports (TCP, HTTP, MSMQ, named pipes), this common denominator is actually small. In this respect, Nicholas Allen from the WCF team wrote back in 2007:

—Nicholas Allen blog,

http://blogs.msdn.com/b/drnick/archive/2007/05/16/client-ip-address.aspx

It was not surprising to see comments from unhappy developers who expected that such features (e.g., getting the IP address of the client) were just very basic and had to be in the framework.

Finally, and after some initial resistance, these features were added to WCF. But this means that abstractions started to leak. To accommodate all possible cases, WCF started to build and expose many aspects of the underlying transports, and this led to very complex configurations. Configuring a WCF endpoint almost always required consulting the documentation and possibly copying and pasting some configuration from the documentation. At times, configuring a WCF endpoint resembled the switches and knobs of an airplane’s cockpit, where only the exact combination of switches works; otherwise, the plane would crash!

Another consequence of transports leaking back to WCF was that the disposal of the transport-specific system resources got more complicated and resulted in a broken IDisposable implementation where instead of a standard using block to dispose the disposable WCF channels, Microsoft recommended the model shown in Listing 1-2 (source: http://msdn.microsoft.com/en-us/library/aa355056.aspx).

Listing 1-2.  Recommened Disposal Method for WCF Channels

try
{
    ...
    client.Close();
}
catch (CommunicationException e)
{
    ...
    client.Abort();
}
catch (TimeoutException e)
{
    ...
    client.Abort();
}
catch (Exception e)
{
    ...
    client.Abort();
    throw;
}

Having said this, WCF is still used by many teams and is a useful tool when it comes to exposing an RPC or when a WS-* implementation is required. It is now a mature product and has been widely used in the industry. However, Microsoft has not updated it since .NET 4.0 and does not seem to have any plans to add features.

Rage Against the SOAP: HTTP Makes a Comeback

Although SOAP was using HTTP basically apart from the raw transport, it was ignoring it. It used only the POST method,which is not cacheable in any circumstance; hence, systems using SOAP (including WCF) had to build their own caching layer and logic. So in a way it was a waste of a protocol to use only a handful of the features.

Also WS-* made SOAP very bloated and hard to work with. Implementing these standards (there were more than 20 different WS-* standards) was out of reach for all but a few very large vendors. Using these implementations was difficult and required a lot of configuration. So it led to a lot of frustration in the community. Simple was good and Simple Object Access Protocol was anything but simple!

So the industry looked for an alternative for the verbose and full of ceremony SOAP. The answer came in Roy Fielding’s thesis and the RESTful API. Inspired by his writings, a new breed of APIs surfaced that did not have any of the SOAP baggage and were light and extensible. Although initial APIs were not fully RESTful, they were successful attempts to build a system on top of HTTP richness. The community also started to distance itself from SOAP by replacing the term web services with Web API, referring to the fact that this new breed of APIs was web-friendly. As can be seen in Figure 1-1, the interest in Web API started in 2005 and it has recently grown exponentially.

The Flickr API is probably one of the first public non-SOAP HTTP APIs, dating back to 2004. However, arguably the most groundbreaking API was Amazon S3, which was launched on March 1, 2006. This was a commercialization of Amazon’s internal IT infrastructure as a cloud platform exposing the services via a RESTful API. By 2008, REST was a hot topic among HTTP enthusiasts and, at the time of writing this book, it has gained a wide adoption and is no longer a novelty.

During the past few years, Web API, and particularly REST/HTTP API, has been a very hot topic in the computer community, leading to heated debates on what a RESTful implementation means in practice. Regardless of all the debates and controversies on the edge cases, HTTP has been delivering a premium value in the new Web and cloud-based systems.Emergence of powerful smartphones and advances in HTML5/JavaScript/CSS3 programming techniques have led to the introduction of premium experience in web applications consuming HTTP APIs.

Another area that helped the adoption of HTTP API was the emergence of identity protocols that were fully based on the HTTP programming paradigm and free of any SOAP or WS-* ceremony. The work on OAuth and OpenID started around 2006, but it took a few years for them to mature. Explosion of the social media (Facebook, Twitter, etc.) meant that many web users already had a login with one of the social media sites, and they could authenticate or interact with other sites or applications.

HTTP, which was designed for distributed computing, returned fully to the picture of interoperable APIs.

WCF REST

In the meantime, Microsoft, which had invested heavily in WCF, could not ignore what was happening in the community. Many were moving away from RPC and joining the REST movement. In an attempt to appease the REST enthusiasts among the WCF adopters, the WCF team developed WCF REST in 2008. This was released as the WCF Starter Kit, which worked with .NET 3.5.

WCF REST, by mixing RPC and REST, which were two different and opposing paradigms, inherently could not be successful because it was built on a paradox (see Table 1-3). As a result, it did not succeed in practice, and many adopters soon found themselves fighting against the framework to satisfy REST.

webHttpBinding in WCF

.NET 3.5 included a binding that was not talking SOAP: webHttpBinding. It was capable of sending or receiving plain old XML over HTTP (POX) or JSON.

Although this was not RESTful and similar to SOAP, only the POST verb was supported, and it allowed for consumption of WCF API by JavaScript-enabled devices.

WCF Web APIs

After finishing his work in the Microsoft Extensibility Framework (MEF), Glenn Block joined the WCF Web API team to create success from the failure of WCF REST. Initial Community Technical Preview (CTP) versions of WCF Web API received a lot of positive feedback from the community and encouraged the team to move forward. The first preview was released in October 2010 and the latest one was version 6, which was released in November 2011.

As the work progressed, it became evident that fitting a pure HTTP model into the constraints of WCF/RPC is very hard, if not impossible. On the other hand, the work involved to make HTTP a first-class citizen of the framework and exposing all the power as type-safe classes, properties, and methods had a lot more to do with the Web than WCF. As such, it was decided to rename the framework as ASP.NET Web API and move the work to the ASP.NET team. This coincided with the release of version 6 in November 2011.

Birth of ASP.NET Web API

After the integration of Web API into the ASP.NET team, the framework gained even more popularity. The team worked closely with the community and nightly builds were available. The team released a single beta version followed by the RTM (release to manufacturing) in August 2012.

In HTTP/REST, we have resources, and each resource is identified by a Unique Resource Identifier (URI).ASP.NET Web API uses the familiar programming model of ASP.NET MVC and implemented resources as methods, or more specifically, actions within controllers. As stated earlier, there is an impedance mismatch between RPC and HTTP/REST. Although ASP.NET Web API internalizes the richness of the HTTP and treats it as a first-class citizen, there was still bound to be a clash of the RPC paradigm because resources are implemented as methods (see Figure 1-2).

So let’s have a look at the task at hand. The team had to turn this pair (this is just a random HTTP request/response pair example with the site name anonymized):

POST /ajax/bz HTTP/1.1
Host: www.example.com
Connection: keep-alive
Content-Length: 477
Origin: https://www.example.com
User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) _ Chrome/27.0.1453.116 Safari/537.36
Content-Type: application/x-www-form-urlencoded
Accept: */*
Referer: https://www.example.com/messages/ ...
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-GB,en;q=0.8,en-US;q=0.6
Cookie: datr=...

HTTP/1.1 200 OK
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: application/x-javascript; charset=utf-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
Strict-Transport-Security: max-age=60
Content-Encoding: gzip
Date: Sun, 30 Jun 2013 11:28:31 GMT
Transfer-Encoding: chunked
Connection: keep-alive
...

into some form of this:

public Baaz Foo(Bar bar)
{
        ...
}

This clearly demonstrates the impedance mismatch between RPC and HTTP and the big task at hand. The initial approach used to solve this problem was to wrap the input parameter and return value into a generic “envelope:”

public HttpResponseMessage<Baaz> Foo(HttpRequestMessage<Bar> request)
{
        ...
}

These envelopes would be able to support and supply additional aspects of HTTP request and response while staying loyal to the type safety of the method parameters.

This in fact was the original approach even after the release of the ASP.NET Web API beta. However, after a while, it became apparent that maintaining the same generic type for the response through the chain of the HTTP processing pipeline was impractical. In other words, the content of the response could change while the response was passing through the HTTP pipeline; hence, having a generic request and response would both pose technical challenges with the async model as well as not being logically correct.

So the team decided to remove the generic parameter from the request and response and allow the generic type to be expressed in the Content property (which models the request and response payload or in HTTP jargon the “entity”). So our example of the action method could be rewritten (we have used the async pattern, which will be covered in Chapter 2):

public async Task<HttpResponseMessage> FooAsync(HttpRequestMessage request)
{
        var bar = await request.Content.ReadAsAsync<Bar>();
        ...
        var  response = request.CreateResponse();
        response.Content = new ObjectContent<Baaz>(new Baaz());
        return response;
}

This model solves the impedance mismatch. But that is not the only solution. ASP.NET Web API uses other techniques to model other axes not available in an action method. Also it is important to note that unlike ASP.NET MVC actions, ASP.NET Web API actions can return any type and they do not have to inherit from the ActionResult type. Let’s examine the ASP.NET Web API architecture to understand those techniques.

Architectural Features

The ASP.NET Web API team made some key decisions that have led to the framework’s robustness, modularity, and testability. Some of these decisions include:

• Async all the way: The ASP.NET Web API framework has been designed using the task-based asynchronous programming model from the top to the bottom. As we’ll see in Chapter 2, this leads to increased scalability.
• No more HttpContext.Current: Although ASP.NET MVC has wrapped HttpContext inside HttpContextBase for better testability, ASP.NET Web API takes this even further and stores all contextual properties of the request in the Request.Properties dictionary. Although accessing HttpContext in ASP.NET Web API could still work, use of HttpContext.Current is strongly discouraged due to the possible loss of context in task-based async thread switching.
• Replicating the same HTTP pipeline in client library as well as server library: This helps with unifying the programming model as well as ease of integration testing because you can short circuit the client–server communication and bypass the network by connecting the client pipeline directly to the server pipeline (this will be covered in Chapter 15).
• Ability to host both in IIS (or development server) and in any nonweb server process (called self-hosted) : Future versions of ASP.NET Web API will have the ability to be hosted in custom web servers. We’ll look into this in Chapter 17.
• Built-in support for dependency injection: ASP.NET Web API supports any custom dependency injection framework through a simple service location interface. We cover dependency injection in Chapter 14.
• Service location even for components of the framework itself: You can customize many elements of ASP.NET Web API by supplying your own custom implementation. We cover this feature in Chapter 14.
• Ultimate testability: ASP.NET Web API has been designed with testing in mind. Almost all parts of the framework are testable, and we’ll cover unit testing in Chapter 15.
• HttpConfiguration: The ASP.NET Web API runtime context is abstracted and represented in the HttpConfiguration class. HttpConfiguration is a central place for defining different aspects of the runtime and does not have static properties, making it more testable. Important contextual properties include:

• Routes
• Message handlers
• Global filters
• Formatters
• Dependency resolver
• Parameter binding providers

ASP.NET Web API Elements

ASP.NET Web API has been built to map the web/HTTP programming model to the .NET Framework programming model. For solving these problems, it sometimes uses familiar constructs introduced in ASP.NET MVC, such as Controller, Action, Filter, and so forth. In other cases, it creates its own abstractions, which we’ll mention here but fully discuss in the upcoming chapters.

Figure 1-3 shows an example request and the mapping of HTTP constructs to the ASP.NET Web API abstractions. We’ll look into some of the key ASP.NET Web API abstractions so that we can see the big picture.

HTTP Processing Pipeline

The ASP.NET Web API processing pipeline is based on a simple pipe-and-filter abstraction. Pipe-and-filter or simply pipeline is a design pattern where components will process the incoming request sequentially and each component’s output is the next component’s input. Figure 1-4 demonstrates a request/response pipeline; this model is shown in two different representations.

Because each component passes the pipeline once for the request and again for the response (in the reverse order), the ASP.NET Web API team chose the Russian doll model as a more descriptive and fitting analogy. Russian dolls, or Matryoshka dolls, are wooden figurine dolls of decreasing size where each doll fits inside the doll next in size (see further discussion in Chapter 10).

Every component, upon receiving the request, has two choices: to pass it on to the next component in the chain and receive the response when it passes back, or to cut off the chain and return the response. The last component does not have a choice and has to do the latter. This concept is similar to the concept of HTTP modules and HTTP handlers, but here these two have been combined. This has been modeled in the abstract class HttpMessageHandler. The magic of the message handler is in its single async method, which receives the request and returns a Task<HttpResponseMessage>:

protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request,   CancellationToken cancellationToken)
{
        ...
}

In any hosting scenario, an implementation of HttpServer (a class inherited from HttpMessageHandler) will receive the request. HttpServer will pass the request through a series of message handlers defined in the runtime (against HttpConfiguration) and then normally would pass it to the HttpControllerDispatcher. At the end, the HttpServer will receive the response and send it back to the user.

Public API

With the growing popularity of REST API, companies are quickly moving toward making their services available through a pure HTTP API. In these cases, HTTP API is usually used in conjunction with SOAP API and sometimes only HTTP API is supported.

In recent years, the biggest public APIs have been mainly implemented in pure HTTP. Twitter, Facebook, Amazon, Google, Flickr, Netflix, and many more have the REST API as their main public API. Most of these APIs implement OAuth or OAuth 2.0 rather than the heavy WS-* protocols over SOAP. As mentioned earlier, the OAuth protocol helped with the adoption of HTTP API over SOAP.

The ProgrammableWeb web site (www.programmableweb.com/) is dedicated to registering public APIs (mainly RESTful), and since its launch in 2005, it has registered around 10,000 APIs and 7,000 mashups (see Figure 1-6).

Nowadays companies with existing SOAP public APIs are adding REST endpoints to their systems. If your company has a public API, using ASP.NET Web API for exposing your services is a very wise investment.

Middleware and Internal API

As Daniel Jacobson, Greg Brail, and Dan Woods explain in their excellent book API: A Strategy Guide (O’Reilly 2011), public APIs are only the tip of the iceberg of all APIs. They firmly believe the real benefits of APIs are materialized in the private and internal APIs within enterprises and organizations.

As explained earlier, HTTP was designed with distributed computing in mind. A lot of enterprises had to reinvent the wheel when it comes to caching, concurrency, security, compression, and encryption, while HTTP has all of those to offer out of the box. We strongly believe that ASP.NET Web API will gradually replace most of the existing WCF (and ASMX) services in the next three to five years.

Modern Web Application API

Web programming is in a much different place that it had been five years ago. Emergence of smart devices and adoption of better JavaScript techniques and libraries have opened the avenue for heavy client-side programming, relying less and less on the server for driving application logic.

A type of web application called Single Page Application (SPA)has gained a lot of popularity (Gmail is a famous example of SPA). In this type of application, the server only provides static HTML views and templates and JavaScript and then the application starts to load the data by calling the server API using Ajax. All navigation and subsequent loading of different views are handled without a single full post back to the server. SPA is usually used with a Model-View-Controller JavaScript library/framework such as Backbone.js, AngularJS, or Knockout.js (the latter known as a Model-View-ViewModel library).

ASP.NET Web API in its short lifespan has become a popular data provider for these types of applications. Because views are rendered on the client using JavaScript templating rather than on the server, ASP.NET Web API is a perfect fit for providing raw data.

On closer examination, we will find that in many cases a nicely designed public API can be equally used as a data provider for SPAs. Such an API can provide a lot of value by serving B2B customers as well as various customer devices and desktop applications.

Cloud Services

As pointed out earlier, the release of Amazon Web Services (AWS) was an important milestone in the adoption of REST. Microsoft’s Windows Azure platform provides its services through both a RESTful API and client SDKs (AWS also has client SDKs), where the client SDK is just a wrapper around the API call.

ASP.NET Web API has been a popular framework for exposing Azure cloud applications, and Microsoft is working toward better integration between these two frameworks. For a tutorial on the subject, visit the Windows Azure web site at www.windowsazure.com/en-us/develop/net/tutorials/rest-service-using-web-api/.

Services for Native Apps

As stated earlier, smartphones had an important part in the trend toward simpler pure HTTP API and away from SOAP. Many of the native apps can be likened to dumb terminals connected to a big mainframe, with the mainframe being the cloud. In these apps, the cloud provides storage and server-side processing and the app is mainly used for the consumption of the services exposed by an API.

If you are thinking of building an app for smartphones, you should seriously consider exposing your backend services through a REST API using ASP.NET Web API.

Self-Hosted HTTP Server

Before ASP.NET Web API, there was no easy way to host a simple web server in your Windows service or desktop application. If you needed to host a service, you had to use WCF, which was not ideal.

ASP.NET Web API has made it extremely easy to host your API in a nonweb server process. Most of the code you need to write is exactly the same as the code you would write in a web-hosted scenario. You can also use the self-hosted Web API server to serve static resources or even a server-rendered view (e.g., Razor) so you can serve web pages. A common scenario is when you have a process running as a Windows service and you need a web-based administration console for it, in which case the self-hosted Web API is all you need.

ASP.NET Web API and ASP.NET MVC

As stated earlier, there is a considerable similarity between ASP.NET Web API and ASP.NET MVC. Having said that, there is not a great deal of functional overlap between them, but a question that crops up time and time again is the choice between these two independent frameworks.

If you have tried the ASP.NET Web API template in the Visual Studio, you have probably noticed that this template combines ASP.NET Web API and ASP.NET MVC. In fact, nothing stops you from using both of these frameworks in the same project. But you need to be clear about what the main value of each framework is.

ASP.NET MVC is ideal for generating server-side views (Razor or Web Forms). And in terms of processing client-side data, it is mainly geared toward x-www-form-urlencoded data (form post data). Although ASP.NET Web API can process x-www-form-urlencoded data and can generate Razor views, it is best for exposing an API.

If you have both these requirements in a project, use both frameworks in conjunction.

ASP.NET Web API and DDD

Since its formalization in 2003, Domain-Driven Design (DDD) has provided the vocabulary, semantics, and conceptual tools for designing and architecting modern software. Eric Evans introduced DDD in his book Domain-Driven Design: Tackling Complexity in the Heart of Software (Addison-Wesley 2003), which has earned classic status among computer software books along with the Gang of Four design patterns book (Design Patterns: Elements of Reusable Object-Oriented Software, by Erich Gamma et al., Addison-Wesley 1994) and Martin Fowler’s Patterns of Enterprise Application Architecture (Addison-Wesley 2002).

DDD introduced strategic design, which is a collection of patterns and practices important in designing SOA. According to DDD, each of the bounded contexts in your enterprise would be mapped to a service in your domain, and the service would be exposed through its API.

If you are using ASP.NET Web API to build exposure to your domain, you should seriously consider designing your API in such a way that it completely hides the complexity of your bounded context. Client-Server Domain Separation (CSDS) is an architectural style inspired by REST and DDD that advocates that the client and server should live in their own bounded context.

The server is responsible for defining and maintaining its state and hides its complexity behind its API (see Figure 1-7). The client can interact with (query or modify) the state only through the public API. The server does not know the nature of the client, as the client could be a browser, native mobile application, or another server. This separation leads to better decoupling and a more maintainable system.

ASP.NET Web API and CQRS

Command Query Responsibility Segregation (CQRS) is a pattern in software design and architecture that advocates separation of reads from writes and claims this leads to more scalable software. So the change in the state is carried out by the commands, while reads are carried out by the queries.

CQRS is also associated with other design practices. For example, reads are usually served by a denormalized data store separate from the write store and in a different format.

Historically, CQRS systems have used the service bus to deliver messages. Although this can be the case in a closed enterprise, a public API would need open connectivity where HTTP is a superior choice. In fact, HTTP already has the semantics for a CQRS design.

On the one hand, HTTP has GET as a safe verb for queries and unsafe verbs (PUT, POST, and DELETE) for commands. In HTTP, a safe verb is a verb that does not result in a change in state (see Chapter 3 for a more detailed discussion).

On the other hand, idempotency is an important aspect of designing messages in CQRS. An operation is considered idempotent where its execution once or multiple times has the same effect. So in a CQRS system, you can use POST for a nonidempotent command and PUT for an idempotent command.

Even HTTP status codes are suitable for expressing CQRS results. For example, a successful GET operation would normally return the denormalized data with a 200 (OK) status code, while a command would return no data and send back status code 202 (Accepted), which signifies an asynchronous operation.

So if you are designing a CQRS system and you need to expose your commands and queries outside your internal network, consider using ASP.NET Web API. By doing that, you can take advantage of caching your queries (GET) and concurrency-aware commands (PUT) for free.

ASP.NET Web API and Transactions

Databases have traditionally supported transactions over the past three decades. Transactions in classic systems are defined by the acronym ACID (Atomicity, Consistency, Isolation, and Durability). This is how they have ensured that when you make a payment, your balance is not deducted unless your payee receives your payment.

With the rise of distributed systems, maintaining ACID across the boundaries has posed challenges that are hard to solve. A service is normally dependent on other services, and in its traditional form, a transaction between two services will involve a cascade of systems and lock resources, reducing scalability. However, transactions are a fact of life, so systems have to support transactions, although in a looser form. As such, the acronym BASE (Basic Availability, Soft state, and Eventual consistency) describes a looser form of transactions, and BASE implementations have been widely used across many big SOA systems, such as the Amazon web site.

HTTP/REST (and hence ASP.NET Web API) can be used to interface transactions in an SOA. Cesare Pautasso and Guy Pardon have proposed an implementation that involves a state machine moving through states using HTTP calls. This proposal involves a mediator where you can obtain a token when using POST, confirm the transaction using PUT, or cancel it using DELETE. For more information, visit his presentation at www.inf.usi.ch/faculty/pautasso/talks/2012/soa-cloud-rest-tcc/rest-tcc.html#/title.

Provide Top-Notch Documentation

Most .NET developers have gotten used to the ease of consuming WCF and web services by adding a service reference to the project or consuming contract libraries. As discussed earlier, WCF is an implementation of RPC that makes it very similar to consuming a library. As such, documentation is normally concerned only with the input and output schemas and possible exceptions or faults.

With the extra flexibility, there are many aspects of a REST service that need to be documented. The good news is that Microsoft has realized the need and the ASP.NET Web API team has been working on making API documentation easier. This feature is covered in Chapter 18.

Just bear in mind that API documentation is the responsibility of the team working on the API. Good documentation is the key for the adoption of a public API.

Publish Schemas

In SOAP, WSDL would normally publish the schema along with the service definition. This is possible because web services assume XML, and XML supports schema. In a REST service, you could be exposing other formats, some of which might not support schema. For example, although there have been efforts to propose a schema for JSON, this has not yet been widely accepted and adopted.

In any case, it is important to publish schema of your API messages. Some APIs would use examples or plain text documentation for publishing the schema. Make sure you have supplied users of your API with enough information on how to use it.

Plan Your Versioning Strategy

As they say, the only thing that does not change in a system is change itself. With changes come requirements for versioning.

On the one hand, versioning an API is similar to versioning a library. With RPC in mind, calling an API can be very similar to calling a method in a library. On the other hand, publishing and rolling out a library is nothing like publishing an API.

First, avoid changing the version just for the sake of changing it. Commonly, frequent version changes can be a sign of poor domain analysis. If you have to change your version soon after going live, no versioning strategy can help you. What you need is a thorough review of your domain analysis. For example, Amazon S3 API version has stayed the same since its launch in 2006.

Avoid microversioning your API. Granularity of API should be much coarser than you would have in the case of a library. Although this is a very controversial subject, we believe that the top level version needs to be placed in the resource URL itself, especially with a public API, as it is with many APIs such as Google or Twitter.

Consider not upgrading the version if the changes are nonbreaking. As such, prefer nonbreaking changes over breaking ones. If the changes are breaking, change the version but keep running both versions. By providing more functionality in the new versions, you can gradually wean clients off the older versions and then decommission them (see Figure 1-8).

Provide Test Services, Logging, and Tracing Facilities for Consumers

“Treat others as you would like to be treated yourself.” This is certainly true if you have an API used by other teams or other companies! Consider a situation where you are trying to consume an API and having to use the live endpoint for your tests or where you have gone live and you suddenly get errors and do not know what is happening.

Consider providing a test service with a reasonable number of scenarios for the developers integrating your API into their system. Your error information should be descriptive enough and provide as much information as needed for the integrators to be able to trace their issue. A key approach is a thorough validation of the input so you can report the issue in a descriptive manner, although a good API has to validate the input anyway.

Even if your API is free, you should require an API key from the users of your API so you can control the usage and provide logging and tracing per API key.

Heavily Instrument, Benchmark, and Monitor Your API

The API is your application—as far as the server is concerned—so the quality of service (QoS) is really important. Scalability and performance requirements of your API need to be defined and various performances of your API benchmarked and recorded for comparison after any release.

On the other hand, when something goes wrong with the system, you need to be able to respond quickly. This is almost impossible without proper instrumentation of your API implementation. Consider instrumenting your API and storing traces and activity logs. These are your best friends if something goes wrong, which sooner or later it will.

Avoid Publishing Client Libraries if You Can

Exposing a full-blown REST API means a lot more cross-cutting features for the consumers of your API. But as stated earlier, this creates a burden in order for clients to consume all of the features. If you have a public API, this could translate into a slow adoption and integration. A common solution is to provide an RPC client library on top of a RESTful API. This is exactly what many vendors such as Amazon or Microsoft are doing for their cloud services’ APIs.

Providing a client library can improve the uptake on your API but it reduces your agility to update and improve the API. Remember the diagrams about the RPC-REST impedance mismatch and the fact that exposing on top of RPC has to compromise either the simplicity of the RPC API or reduced the set of features. So avoid publishing a client if it is at all possible.