Pro ASP.NET Web API: HTTP Web Services in ASP.NET

604 Pages·2013·24.2 MB·English

by  Tugberk Ugurlu

For your convenience Apress has placed some of the front
matter material after the index. Please use the Bookmarks
and Contents at a Glance links to access them.
Contents at a Glance
About the Authors ��������������������������������������������������������������������������������������������������������������xix
About the Technical Reviewer �������������������������������������������������������������������������������������������xxi
Acknowledgments �����������������������������������������������������������������������������������������������������������xxiii
Introduction ����������������������������������������������������������������������������������������������������������������������xxv
■ Chapter 1: Introduction to ASP�NET Web API ���������������������������������������������������������������������1
■ Chapter 2: Introduction to Asynchronous Programming in �NET �������������������������������������27
■ Chapter 3: HTTP, REST, and Hypermedia ��������������������������������������������������������������������������57
■ Chapter 4: HttpClient �������������������������������������������������������������������������������������������������������75
■ Chapter 5: Sample Application: Application Structure and Domain Model ���������������������95
■ Chapter 6: Sample Application: Building the Web API ���������������������������������������������������141
■ Chapter 7: Sample Application: Building the Wrapper and Web Client �������������������������197
■ Chapter 8: Routing ���������������������������������������������������������������������������������������������������������215
■ Chapter 9: Controllers and Actions ��������������������������������������������������������������������������������231
■ Chapter 10: Message Handlers ��������������������������������������������������������������������������������������275
■ Chapter 11: Filters ���������������������������������������������������������������������������������������������������������289
■ Chapter 12: Media Type Formatters and Model Binding �����������������������������������������������325
■ Chapter 13: Input Validation ������������������������������������������������������������������������������������������365
■ Chapter 14: Dependency Resolution ������������������������������������������������������������������������������415
■ Chapter 15: Unit Testing and Integration Testing ����������������������������������������������������������431
v
■ Contents at a GlanCe
■ Chapter 16: Optimization and Performance ������������������������������������������������������������������463
■ Chapter 17: Hosting �������������������������������������������������������������������������������������������������������517
■ Chapter 18: Tracing, Logging, and API Documentation �������������������������������������������������545
Index ���������������������������������������������������������������������������������������������������������������������������������577
vi
Introduction
If you would like to discover the possibilities offered by HTTP on the .NET Framework, ASP.NET Web API is the
technology for you. This book will get you up to speed on how it works and how to use it at both high and low levels.
We have structured this book to make it really easy to use. If you would like to get your hands dirty quickly,
we recommend that you work through Chapters 1 to 7 in order, because Chapters 5, 6, and 7 are all about building
a sample multitier application using ASP.NET Web API. This sample application is intended as a guide on how to
structure an ASP.NET Web API application in a hosting-agnostic way (from both API and client perspectives). We
recommend you download the source code and run the application locally to begin with. You can download the
source code from www.apress.com/9781430247258 along with all the other code related to this book. Alternatively,
you can get it from GitHub (https://github.com/tugberkugurlu/PingYourPackage) through a Git client (make sure to
check out the “Edition-1” branch). No matter which method you choose, be sure to read the “Run the Application” section
inside the README.md file (https://github.com/tugberkugurlu/PingYourPackage/blob/Edition-1/README.md)
to get the sample application running smoothly.
If you prefer to get into the core of the ASP.NET Web API framework, you can choose to skip the sample
application chapters and go straight to the feature-specific chapters on routing, controllers, message handlers, filters,
and so on. These chapters really dive into the details of the specific parts of the ASP.NET Web API request pipeline and
will give you a deep understanding of how the framework is processing your request.
Required Software
To use this book, you will need:
• .NET Framework 4.5 or higher
• Visual Studio 2012 or later
• Visual Studio Extension: NuGet Package Manager
• Visual Studio Extension: xUnit.net runner for Visual Studio
• SQL Server Express (for sample applications and some other samples)
Any other software we make use of in the book is available through NuGet.
xxv
Chapter 1
Introduction to ASP.NET Web API
The fact that you are reading this means you are interested in learning something about ASP.NET Web API (application
programming interface). Perhaps you are relatively new to web services and want an expansive view. You may already
be familiar with the technology and just need to swim a bit deeper into the Web API waters; hence, you need a beacon
to guide you through unfamiliar places. Or maybe you are already a pro and just want to fill those few gaps in your
knowledge. Wherever you are in this journey, stay tight as we are about to start our ride, and it is going to be fun!
ASP.NET Web API is the new cool kid on the block that gets us all excited. It is the new shiny tool that we love to
use and it would be great to claim experience in it on our CV. But that is not why you should learn about it.
We believe ASP.NET Web API is a technology that is going to change the way we think about and develop our
server applications. It will change how we approach designing and implementing services. It will also affect our
decisions in writing client code. ASP.NET Web API already has a rich and active community around it that is adding
useful building blocks on top of its extensible model. And it is here to stay, as it talks web. So these are some of reasons
why it is necessary to learn about it.
This chapter won’t deal with much code, but not to worry, there will be plenty of opportunities in the upcoming
chapters. But first it is essential to see how ASP.NET Web API is going to fit into the overall picture of modern
web-based architecture as well as middle tier services.
This chapter will start by defining what the ASP.NET Web API is and then move on to the background and
architecture before giving the reasons why you would choose (or not choose) ASP.NET Web API for solving
business solutions.
ASP.NET Web API
This section will briefly explain what ASP.NET Web API is, the libraries that comprised it, and where its source came
from. We keep the more detailed discussion until after we have covered its background in the following section.
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.
1
Chapter 1 ■ IntroduCtIon to aSp.net Web apI
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.
■ Note aSp.net Web apI was released with aSp.net MVC 4 and its implementation has many similarities with
aSp.net MVC. a common mistake is to think of aSp.net Web apI as an extension to aSp.net MVC partly because
Web apI Visual Studio templates can only be accessed by choosing an aSp.net MVC 4 project type. this notion is
incorrect and unhelpful as these two frameworks are completely independent. although they can be used together,
they do not have to be. aSp.net MVC is ideal for serving server-side–rendered views, while aSp.net Web apI is best
used as a web service exposing a service apI.
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.
2
Chapter 1 ■ IntroduCtIon to aSp.net Web apI
Table 1-1. ASP.NET Web API NuGet Packages and Their Dependent Packages
NuGet Package NuGet Dependency (Contains) Use Case
Microsoft.AspNet.WebApi.Core Microsoft.AspNet.WebApi.Client Library development
(System.Web.Http.dll)
Microsoft.AspNet.WebApi.Client Microsoft.Net.Http Consuming HTTP endpoints
Newtonsoft.Json using HttpClient; capable of
(System.Net.Http.Formatting.dll) consuming different formats
Microsoft.AspNet.WebApi.HelpPage Microsoft.AspNet.WebApi.WebHost Creating help pages for your
Microsoft.AspNet.Mvc APIs implemented in ASP.NET
Microsoft.AspNet.Razor Web API
(templates, views, and assets required
for displaying help page)
Microsoft.AspNet.WebApi.OData Microsoft.Net.Http Exposing your data as an
Microsoft.AspNet.WebApi.Client OData HTTP service
Microsoft.AspNet.WebApi.Core
Microsoft.Data.OData
(System.Web.Http.OData.dll)
Microsoft.AspNet.WebApi.SelfHost Microsoft.AspNet.WebApi.Core Creating a Web API service
(System.Web.Http.SelfHost.dll) and exposing it inside a
non-web application as a
self-hosted service
Microsoft.AspNet.WebApi.Tracing Microsoft.AspNet.WebApi.Core Allows the ASP.NET Web API
(System.Web.Http.Tracing.dll) framework to trace to
System.Diagnostics.Trace
Microsoft.AspNet.WebApi.WebHost Microsoft.AspNet.WebApi.Core Hosting Web API in a web
Microsoft.Web.Infrastructure application
(System.Web.Http.WebHost.dll)
Microsoft.Net.Http (System.Net.Http Provides a programming
System.Net.Http.WebRequest) interface for modern HTTP
applications; contains
HttpClient
Newtonsoft.Json (Newtonsoft.Json.dll) JSON serialization and
deserialization
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.
3
Chapter 1 ■ IntroduCtIon to aSp.net Web apI
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.
ASP.NET Web API Background
Now that you know what ASP.NET Web API is and how to get its libraries and source code, let’s look at the context in
which ASP.NET Web API was formed.
As stated earlier, ASP.NET Web API is an implementation of the HTTP specification that enables you to build
an HTTP API on top of the .NET Framework. Considering the HTTP 1.1 specification (which is the latest HTTP spec,
although work on HTTP 2.0 has started) was ratified in 1999, why did it take 13 years for Microsoft to finally provide a
first-class framework to expose the true power of HTTP? We are going to find out with a journey back in time.
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.
4
Chapter 1 ■ IntroduCtIon to aSp.net Web apI
Table 1-2. World Wide Web and HTTP Timeline
Year Event
1945 Vannevar Bush described Memex, the first proto-hypertext system in the article
“As We May Think.”
1960s Systems are built around the hypertext concepts such as Hypertext Editing
System (HES), Project Xanadu, and oN-Line System NLS.
1970 Arthur C. Clarke predicted that satellites would someday “bring the accumulated
knowledge of the world to your fingertips” using a console that would combine
the functionality of the photocopier, telephone, television, and a small computer,
allowing data transfer and video conferencing around the globe.
1980 Tim Berners-Lee built the first system based on hypertext.
1984 Tim Berners-Lee joined CERN to enable collaboration of scientists over the
network in a heterogenous platform environment.
1989 Tim Berners-Lee wrote a proposal on a large hypertext system with typed
hyperlinks.
1990 Robert Cailliau formalized Tim’s proposal and suggested the name
“WorldWideWeb” or W3 for the hypertext project.
1990 Tim Berners-Lee finished building the first working prototype of a web server
and a browser.
1993 Mosaic, the first graphical web browser, is built.
1993 CERN decided WWW will be free.
1994 World Wide Web Consortium is formed at MIT.
1996 HTTP 1.0 specification ratified by W3C as RFC 1945.
1999 HTTP 1.1 specification ratified by W3C as RFC 2616.
2006 Amazon uses RESTful API to expose its public cloud.
2012 Microsoft publishes ASP.NET Web API framework.
Source: Wikipedia http://en.wikipedia.org/wiki/World_Wide_Web
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.
5