An Introduction to ASP.NET Web API
Microsoft recently released the ASP.NET MVC 4.0 beta and along with it, the brand spanking new ASP.NET Web API. Web API is an exciting new addition to the ASP.NET stack that provides a new, well-designed HTTP framework for creating REST and AJAX APIs (API is Microsoft’s new jargon for a service, in case you’re wondering). Although Web API currently ships and installs with ASP.NET MVC 4, you can use Web API functionality in any ASP.NET project, including WebForms, WebPages and MVC or none of the above. You can also self-host Web API in your own applications. Please note that this article is based on pre-release bits of ASP.NET Web API (pre-RC) and the API is still changing. The samples are built against the latest snapshot of the CodePlex ASP.NET Web Stack Source and some of the syntax and functions might change by the time Web API releases. Overall concepts apply, and I’ve been told that functionality is mostly feature complete, but things are still changing as I write this. Please refer to the latest code samples on GitHub for the final syntax of the examples. What’s a Web API and Why Do We Need It? HTTP APIs become increasingly important with the proliferation of devices that we use today. Most mobile devices, like phones and tablets, run apps that use data retrieved from the Web over HTTP. Desktop applications are also moving in this direction with more and more online content and synching and Windows 8 promising an app-like experience. Likewise, many Web applications rely on rich client functionality to create and manipulate the browser user interface, using AJAX rather than server-generated HTML data to load up the user interface with data. Results returned from these remote HTTP services are data rather than HTML markup. This data tends to be in XML or - more commonly today - in JSON (JavaScript Object Notation) format. Web API provides an easy way to build the backend code to handle these remote API calls using a flexible framework that is based very specifically around the semantics of the HTTP protocol. | " |
Most mobile devices, like phones and tablets, run apps that use data retrieved from the Web over HTTP.
| " |
The .NET stack already includes a number of tools that provide the ability to create HTTP service backends. There’s WCF REST for REST and AJAX, ASP.NET AJAX Services purely for AJAX and JSON, and you can always use plain HTTP Handlers for any sort of response but with minimal plumbing. You can also use plain MVC Controller Methods or even ASP.NET WebForms pages to generate arbitrary HTTP output. Although all of these can accomplish the task of returning HTTP responses, none of them are optimized for the repeated tasks that an HTTP service has to deal with. If you are building sophisticated Web APIs on top of these solutions, you’re likely to either repeat a lot of code or write significant plumbing code yourself to handle various API requirements consistently across requests. A Better HTTP Experience ASP.NET Web API differentiates itself from these other solutions in that it was built from the ground up around the HTTP protocol and its messaging semantics. Unlike WCF REST or ASP.NET AJAX with ASMX, it’s a brand new platform rather than bolted-on technology that is supposed to work in the context of an existing framework. Web API is meant to handle any kind of HTTP input and produce output and status codes using the full spectrum of HTTP functionality available. There’s much-improved support for content negotiation based on HTTP Accept headers, with the framework capable of detecting content that the client sends and requests and automatically serving the appropriate data format in return. Many of the features favor convention over configuration, making it much easier to do the right thing without having to explicitly configure specific functionality. Although previous solutions accomplished this using a variety of WCF and ASP.NET features, Web API combines all this functionality into a single server-side HTTP framework that intrinsically understands the HTTP semantics and subtly drives you in the right direction for most operations. And when you need to customize or do something that isn’t automatic, there are overrides for most behaviors, and even many low-level hook points that allow you to plug-in custom functionality with relatively little effort. | " |
ASP.NET Web API differentiates itself from existing Microsoft solutions in that it was built from the ground up around the HTTP protocol and its messaging semantics.
| " |
Web API also requires very little in the way of configuration so it’s very quick and unambiguous to get started. To top it all off, you can also host the Web API in your own applications or services. - Above all, Web API makes it extremely easy to create arbitrary HTTP endpoints in an application without the overhead of a full framework like WebForms or ASP.NET MVC. Because Web API works on top of the core ASP.NET stack, you can plug Web APIs into any ASP.NET application.
| & | | 
By: Rick Strahl Rick Strahl is president of West Wind Technologies in Maui, Hawaii. The company specializes in Web and distributed application development and tools, with focus on Windows Server Products, .NET, Visual Studio, and Visual FoxPro. Rick is the author of West Wind Web Connection, West Wind Web Store, and West Wind HTML Help Builder. He’s also a C# MVP, a frequent contributor to magazines and books, a frequent speaker at international developer conferences, and the co-publisher of CoDe Magazine. For more information please visit his Web site at www.west-wind.com or contact Rick at rstrahl@west-wind.com.
rstrahl@west-wind.com |