In 2012 when Microsoft introduced the ASP.NET WebAPI, I initially became confused about yet another way to generate and transmit content across a HttpRequest. After spending some time thinking about WebAPI over the past week or two and writing a few blocks of sample code, I think I finally have some clarity around my confusion and these are those lessons I learned the hard way.
Old School API - SOAP and ASMX
When ASP.Net launched, the only framework to create and publish content that was available was WebForms. Everybody used it, and it worked well. If you wanted to create an interface for machine-to-machine communications you would create a SOAP service in an ASMX file. You could (and still can) add web references to projects that reference these services. The web reference gives you a first class object with a complete API in your project that you can interact with.
Over time, it became less compelling to build the SOAP services as they transmitted a significant amount of wrapper content around the actual payload you wanted to work with. This extra content was messy, and other programming languages didn't have the tooling support to manage them well. Developers started looking for less complicated alternatives to communicate with connected clients. It turns out that there was another option available that was overlooked by many: HttpHandlers.
HttpHandlers in ASP.NET
HttpHandlers are the backbone of ASP.NET. An HttpHandler is any class that implements the IHttpHandler interface, handles an incoming request, and provides a response to webserver communications. IHttpHandler is a trivial interface with the following signature:
Read more: Codeproject
QR: 