ASP NET web API 2 recipes

www.it-ebooks.info 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 www.it-ebooks.info Contents at a Glance About the Author�������������������������������������������������������������������������������������������������������������� xxv About the Technical Reviewer���������������������������������������������������������������������������������������� xxvii Acknowledgments����������������������������������������������������������������������������������������������������������� xxix Introduction��������������������������������������������������������������������������������������������������������������������� xxxi ■■Chapter 1: Web API in ASP.NET������������������������������������������������������������������������������������������1 ■■Chapter 2: ASP.NET Web API Outside of IIS����������������������������������������������������������������������33 ■■Chapter 3: Routing�����������������������������������������������������������������������������������������������������������57 ■■Chapter 4: Content Negotiation and Media Types������������������������������������������������������������91 ■■Chapter 5: Configuration and Customization�����������������������������������������������������������������129 ■■Chapter 6: Embrace HTTP with ASP.NET Web API����������������������������������������������������������171 ■■Chapter 7: Exceptions, Troubleshooting, and Documenting������������������������������������������205 ■■Chapter 8: Cross Domain and Push Communication�����������������������������������������������������235 ■■Chapter 9: Dependency Injection�����������������������������������������������������������������������������������269 ■■Chapter 10: Securing an ASP.NET Web API Service�������������������������������������������������������283 ■■Chapter 11: Testing Web API Services���������������������������������������������������������������������������317 ■■Chapter 12: OData���������������������������������������������������������������������������������������������������������347 Index���������������������������������������������������������������������������������������������������������������������������������365 v www.it-ebooks.info Introduction Like all of us in this industry, I have been through a ton of programming or framework-centric books in my career as a developer Without a doubt, my favorite type has always been a recipe-style book It might be my low attention span or simply my urge to solve problems rather than read through abstract discussions, but I really enjoy the no-nonsense, straight-to-the-point format of such publications I started working with Web API back when it was still WCF Web API I started blogging about it in the early beta days of the framework, at the beginning of 2012, at which time the name had already changed to ASP.NET Web API Since then I have produced almost 100 blog posts on virtually all aspects of working with ASP.NET Web API, written a fair share of technical articles, been involved in a number of open-source initiatives focused around the framework, and been a speaker at plenty of events But most importantly, I have grown to know Web API better than my own backyard I had some really wonderful feedback from readers and the amazing Web API community, so at some point I started thinking about producing a recipe-style book, as it would feel like a natural extension of the material from the blog A number of plans and approaches were drafted and discussed, and things eventually came to fruition last winter, when this book was officially announced It has never been my intention to write an A-Z compendium or reference book about ASP.NET Web API Instead, I reveled in the opportunity to use the problem-solution format of the recipe-style book In my mind, it makes the book a much more enjoyable read, as you can cherry-pick the things you are interested in, rather than go through the entire book in a linear fashion You will not find theoretical divagations about architecture or abstract academic discussions about REST in this book Instead, I focus on the problems stated in each recipe and how to solve them with ASP.NET Web API The book dissects what is going on under the hood in the framework and shows you how to push ASP.NET Web API to its absolute limits It is also a framework-centric book; it focuses on how to things specifically with ASP.NET Web API Each of the 103 recipes in the book has dedicated source code illustrating the technique or problem discussed in the recipe To make it easier to follow the book in a non-linear fashion, the solutions are not dependent on each other Each example is simple, straight to the point, and entirely self-contained This allows for the important bits to clearly stand out Due to the nature of the format of the book, the space available for each recipe is constrained, and as such, some of the topics cannot be covered in depth In those cases, I lay out the basics to help you get started, and then point to extra resources and further reading There were many recipe-style books that helped me in my career, and I sincerely hope that this book will help you become a better ASP.NET Web API programmer, too If at least a single recipe helps you avoid some headache that the framework might have given you before, I will be absolutely thrilled xxxi www.it-ebooks.info Chapter Web API in ASP.NET This chapter discusses using ASP.NET Web API on top of IIS, within the ASP.NET runtime The recipes covered in this chapter deal with ASP.NET runtime specifics and, unless noted otherwise, the solutions presented here cannot be extended onto other Web API hosts You will learn how to the following: • Use ASP.NET Web API in the same process as ASP.NET MVC or ASP.NET Web Forms (Recipes 1-1 and 1-2) • Deal with HTML forms and validation (Recipes 1-3 and 1-6) • Link between MVC and Web API controllers (Recipe 1-4) • Use scaffolding to rapidly bootstrap ASP.NET Web API projects (Recipe 1-5) • Introduce ASP.NET-based CSRF (Cross-Site Request Forgery) protection to your Web API (Recipe 1-7) • Work with traditional ASP.NET sessions in ASP.NET Web API (Recipe 1-8) On the other hand, all of the host-agnostic features of Web API (routing, model binding, content negotiation, security, exception handling, and many others) are covered in detail in the upcoming chapters 1-1 Add ASP.NET Web API to an MVC Application Problem You would like to integrate ASP.NET Web API into your ASP.NET MVC project Solution ASP.NET Web API used to be automatically bundled in MVC project templates in Visual Studio 2012 Since Visual Studio 2013, you compose your ASP.NET web application using the new One ASP.NET project wizard, based on Microsoft’s concept of a unified ASP.NET platform, where you can select the relevant components, such as MVC and Web API This is shown in Figure 1-1 www.it-ebooks.info Chapter ■ Web API in ASP.NET Figure 1-1.  The One ASP.NET project wizard, with MVC and Web API in a single project Interestingly, if you choose the Web API project template, MVC will be automatically bundled into it as well, as ASP.NET Web API Help Pages rely on MVC to serve content You can also add Web API to any existing MVC project by installing it from NuGet   Install-Package Microsoft.AspNet.WebApi   Semantically, both approaches to including Web API in an ASP.NET web application project are equivalent because the project wizard simply installs ASP.NET Web API from NuGet too How It Works Under the hood, ASP.NET Web API is built around an asynchronous HTTP handler called System.Web IHttpAsyncHandler, which is shown in Listing 1-1 Handlers are the backbone of ASP.NET; they are classes that can intercept and handle HTTP requests made to the web server and respond to the client with the relevant response Listing 1-1.  Definiton of IHttpAsyncHandler public interface IHttpAsyncHandler : object, IHttpHandler { System.IAsyncResult BeginProcessRequest(HttpContext context, System.AsyncCallback cb, object extraData); void EndProcessRequest(System.IAsyncResult result); }   www.it-ebooks.info Chapter ■ Web API in ASP.NET In fact, this is not much different from the architecture of the ASP.NET MVC framework, which also sits on top of an HTTP handler As a result, while both frameworks are complex pieces of software engineering, they are not any more special than regular IHttpHandler or IHttpAsyncHandler implementations that you might have created in the past to handle your various custom HTTP-based tasks The outline of the Web API IHttpAsyncHandler HttpControllerHandler and its public members is shown in Listing 1-2 Listing 1-2.  Public Members of HttpControllerHandler public class HttpControllerHandler : HttpTaskAsyncHandler { public HttpControllerHandler(RouteData routeData); public HttpControllerHandler(RouteData routeData, HttpMessageHandler handler);   public override Task ProcessRequestAsync(HttpContext context); }   The main difference between MVC and Web API is that since version of the framework, the Web API handler, HttpControllerHandler, is a subclass of HttpTaskAsyncHandler, while the MVC version, MvcHandler, implements IHttpAsyncHandler directly HttpTaskAsyncHandler is NET 4.5 only, which is the only NET version supported by Web API When you run both MVC and Web API in the same ASP.NET process, ASP.NET will use the HttpApplication MapRequestHandler event to determine which of the HTTP handlers will be selected to handle the incoming request At this stage, route matching happens, and the request flows through the IRouteHandler relevant for the selected route The sole purpose of IRouteHandler is to produce an IHttpHandler that can handle the request If the IRouteHandler is HttpControllerRouteHandler (Web API route), then the Web API path will be chosen and the request will end up in the HttpControllerHandler Conversely, if the route handler is MvcRouteHandler, then the MVC path takes over via MvcHandler The Code With the setup showed in this recipe, ASP.NET MVC and ASP.NET Web API will run in the same process so they can easily share state, such as static objects or Global.asax events Additionally, the web.config is common for both frameworks Listing 1-3 shows two controllers, an MVC controller and a Web API controller, which can coexist side by side in a single ASP.NET web application Notice that since they are located in different namespaces, they can even have the same name Moreover, it’s perfectly fine for them to share the same model (DTO) when necessary Listing 1-3.  Sample MVC and Web API Controllers public class Book { public int Id public string public string public string }   { get; set; } Author { get; set; } Title { get; set; } Link { get; set; } www.it-ebooks.info Chapter ■ Web API in ASP.NET namespace Apress.Recipes.WebApi.Controllers.Mvc { public class BooksController : Controller { public ActionResult Details(int id) { var book = Books.List.FirstOrDefault(x => x.Id == id); if(book == null) return new HttpNotFoundResult();   return View(book); } } }   namespace Apress.Recipes.WebApi.Controllers.WebApi { public class BooksController : ApiController { public Book GetById(int id) { var book = Books.List.FirstOrDefault(x => x.Id == id); if (book == null) throw new HttpResponseException(HttpStatusCode.NotFound);   return book; } } }   The key to avoiding conflict between the frameworks is a careful route setup; to facilitate that, by default ASP.NET Web API will occupy URI space under /api, while all of the other root-level URLs will be handled by MVC Typically Web API routes are defined in the WebApiConfig static class against the HttpConfiguration object and its Route property, while MVC routes are defined in the static RouteConfig class, directly against the System.Web.RouteCollection The default route definitions for both frameworks are shown in Listing 1-4 Listing 1-4.  Default Routing for Web API and MVC //Web API routing configuration public static class WebApiConfig { public static void Register(HttpConfiguration config) { // Web API configuration and services   // Web API routes config.MapHttpAttributeRoutes();   www.it-ebooks.info Chapter ■ Web API in ASP.NET config.Routes.MapHttpRoute( name: "DefaultApi", routeTemplate: "api/{controller}/{id}", defaults: new { id = RouteParameter.Optional } ); } }   //MVC routing configuration public class RouteConfig { public static void RegisterRoutes(RouteCollection routes) { routes.IgnoreRoute("{resource}.axd/{*pathInfo}");   routes.MapRoute( name: "Default", url: "{controller}/{action}/{id}", defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional } ); } }   Chapter is dedicated to routing, but with the setup from Listing 1-4, the following endpoints are now exposed by your ASP.NET application: • /api/books/{id} will route to ASP.NET Web API • /books/details/{id} will route to ASP.NET MVC 1-2 Add ASP.NET Web API to a Web Forms Application Problem You would like to integrate ASP.NET Web API into your ASP.NET Web Forms application Solution For new Web Forms projects, in Visual Studio 2013, you can simply choose to include ASP.NET Web API in the new One ASP.NET project wizard, as shown in Figure 1-2 www.it-ebooks.info Chapter ■ Web API in ASP.NET Figure 1-2.  ASP.NET project wizard, with Web Forms and Web API hosted side by side Since ASP.NET Web API is available on NuGet, it can also easily be added to an existing Web Forms solution:   Install-Package Microsoft.AspNet.WebApi   The same applies to using Visual Studio 2012; you can just create a new Web Forms project, and throw in Web API through NuGet How It Works Similarly to using ASP.NET Web API alongside MVC, adding it to a Web Forms project results in Web API running in the same ASP.NET process as the Web Forms application Installing the Microsoft.AspNet.WebApi NuGet package into your ASP.NET project will add a WebApiConfig static class to the App_Start folder It is used for configuring ASP.NET Web API and declaring ASP.NET Web API routes Additionally, the following line, invoking the Web API configuration, gets added to the Application_Start block of the Global.asax:   GlobalConfiguration.Configure(WebApiConfig.Register);   Running Web API inside a Web Forms application is no different than running it inside an MVC application; each request will still be handled by a relevant IHttpHandler This could either be the Web API-specific HttpControllerHandler, or a Web Forms-supplied handler Web Forms map the ASPX extension to www.it-ebooks.info ... are now exposed by your ASP. NET application: • /api/ books/{id} will route to ASP. NET Web API • /books/details/{id} will route to ASP. NET MVC 1 -2 Add ASP. NET Web API to a Web Forms Application Problem... integrate ASP. NET Web API into your ASP. NET Web Forms application Solution For new Web Forms projects, in Visual Studio 20 13, you can simply choose to include ASP. NET Web API in the new One ASP. NET. .. as shown in Figure 1 -2 www.it-ebooks.info Chapter ■ Web API in ASP. NET Figure 1 -2.   ASP. NET project wizard, with Web Forms and Web API hosted side by side Since ASP. NET Web API is available on