Download
Introduction
Why Should You Read This Book?
Web API development is exploding. Companies are investing in droves to build systems
that can be consumed by a range of clients over the Web. Think of your favorite website,
and most likely there’s an API to talk to it. Creating an API that can talk over HTTP is
very easy. The challenge comes after you deploy the first version. It turns out that the
creators of HTTP thought a lot about this and how to design for evolvability. Both media
types and hypermedia were central to the design for this reason. But many API authors
don’t think or take advantage of this, deploying APIs that introduce a lot of coupling in
the client and that don’t utilize HTTP as they should. This makes it very difficult to
evolve the API without breaking the client. Why does this happen? Often because this
is the easiest and most intuitive path from an engineering standpoint to get things done.
However, it is counterintuitive in the long term and against the fundamental principles
with which the Web itself was designed.
This is a book for people who want to design APIs that can adapt to change over time.
Change is inevitable: the API you build today will evolve. Thus, the question is not if,
it is how. The decisions (or nondecisions) you make early on can drastically influence
the answer:
• Will adding a new feature break your existing clients, forcing them to be upgraded
and redeployed, or can your existing clients continue to operate?
• How will you secure your API? Will you be able to leverage newer security
protocols?
• Will your API be able to scale to meet the demands of your users, or will you have
to re-architect?
• Will you be able to support newer clients and devices as they appear?
These are the kinds of questions that you can design around. At first glance you might
think this sounds like Big Design Up Front or a waterfall approach, but that is not at all
the case. This is not about designing the entire system before it is built; it is not a recipe
for analysis paralysis. There are definitely decisions that you must make up front, but
they are higher level and relate to the overall design. They do not require you to un‐
derstand or predict every aspect of the system. Rather, these decisions lay a foundation
that can evolve in an iterative fashion. As you then build the system out, there are various
approaches you can take that build on top of that foundation in order to continually
reinforce your goal.
This is a book of application more than theory. Our desire is for you to walk away with
the tools to be able to build a real, evolvable system. To get you there, we’ll start by
covering some essentials of the Web and web API development. Then we’ll take you
through the creation of a new API using ASP.NET Web API, from its design through
implementation. The implementation will cover important topics like how to imple‐
ment hypermedia with ASP.NET Web API and how to perform content negotiation.
We’ll show you how to actually evolve it once it is deployed. We’ll also show how you
can incorporate established practices like acceptance testing and test-driven develop‐
ment and techniques such as inversion of control to achieve a more maintainable code
base. Finally, we’ll take you through the internals of Web API to give you a deep un‐
derstanding that will help you better leverage it for building evolvable systems
Part I, Fundamentals
Chapter 1, The Internet, the World Wide Web, and HTTP
This chapter starts with a bit of history about the World Wide Web and HTTP. It
then gives you a 5,000-foot view of HTTP. You can think of it as a “Dummies’ Guide”
to HTTP, giving you the essentials you need to know, without your having to read
the entire spec.
Chapter 2, Web APIs
This chapter begins by giving a historical context on web API development in gen‐
eral. The remainder of the chapter discusses essentials of API development, starting
with core concepts and then diving into different styles and approaches for de‐
signing APIs.
Chapter 3, ASP.NET Web API 101
This chapter discusses the fundamental drivers behind ASP.NET Web API as a
framework. It will then introduce you to the basics of ASP.NET Web API as well as
the .NET HTTP programming model and client.
Chapter 4, Processing Architecture
This chapter will describe at a high level the lifecycle of a request as it travels through
ASP.NET Web API. You’ll learn about each of the different actors who have a part
in processing different aspects of the HTTP request and response.
Part II, Real-World API Development
Chapter 5, The Application and Chapter 6, Media Type Selection and Design
These chapters discuss the overall design for the Issue Tracker application. They
cover several important design-related topics including media type selection and
design, as well as hypermedia.
Chapter 7, Building the API and Chapter 8, Improving the API
These chapters will show how to actually implement and enhance the hypermediadriven
Issue Tracker API using ASP.NET Web API. They introduce you to how to
develop the API using a behavior-driven development style.
Chapter 9, Building the Client
This chapter focuses entirely on how to build out a hypermedia client, which can
consume the Issue Tracker API.
Part III, Web API Nuts and Bolts
Chapter 10, The HTTP Programming Model
This chapter will cover in depth the new .NET HTTP programming model on which
ASP.NET Web API rests entirely.
Chapter 11, Hosting
This chapter covers all the different hosting models that exist for ASP.NET Web
API, including self-host, IIS, and the new OWIN model.
Chapter 12, Controllers and Routing
In this chapter you’ll take a deep dive into how Web API routing works and how
controllers operate.
Chapter 13, Formatters and Model Binding and Chapter 14, HttpClient
These chapters cover everything you need to know about model binding and about
using the new HTTP client.
Chapter 15, Security and Chapter 16, The OAuth 2.0 Authorization Framework
These chapters cover the overall security model in ASP.NET Web API and then talk
in detail about how to implement OAuth in your API.
Chapter 17, Testability
This chapter will cover how to develop in ASP.NET Web API in a test-driven man‐
ner.
