Tag Archives: .net tutorial

ASP.NET Web API: Client-Side Pipeline

power-sass-multi-deviceMicrosoft .NET Framework technologies that support a request-response pattern typically use a pipeline, which is a sequence of events that fire to process a request and send back an appropriate response.

Pipelines are important because they allow developers to run code at various stages of processing a request.

The ASP.NET Web API has a pipeline and, by taking advantage of how the API processes HTTP messages, you can easily add some very useful functionality. The Web API has a processing pipeline for both the client and >the server, and this article will focus on the Client-Side Pipeline!

Client-Side Pipeline

The Web API pipeline has two “sides” to it: the client-side and the server-side. Understanding the client-side pipeline is useful as virtually any application can harness the client-side objects to make calls to a Web API. The objects available in the client-side pipeline are especially useful when creating applications that need to access Web API services directly from application code and consume the results.

HttpClient

The HttpClient object represents the client making the request. You can instantiate the object in code, use it to generate an HttpRequestMessage, and send it asynchronously to a URL to be handled by a Web API application. The HttpClient then receives an HttpResponseMessage and handles the contentsaccordingly.

The HttpClient only has four properties, and its methods are primarily concerned with various ways to send an HTTP request and receive a response. The HttpClient is somewhat analogous to AJAX frameworks that essentially facilitate sending requests and receiving responses, leaving it to other code to unpack the response and use the data meaningfully. In the same way, the bulk of the logic dealing with a service response will operate on the HttpResponseMessage object, which will contain the actual data that the requestor needed.

NOTE: With the popularity of various AJAX libraries, many applications will make client-side calls to the Web API directly, but if you have a need to make these calls using server-side code, the HttpClient object will beuseful.

HttpMessageHandler

The HttpMessageHandler object sends the HttpRequestMessage generated by the HttpClient to the right place and listens for an HttpResponseMessage. When a response is received, the HttpMessageHandler is the first object to process it before handing it back to the HttpClient.

HttpMessageHandler is actually a base class for all such handlers. The default implementation for the client-side pipeline is the HttpClientHandler, which satisfies most basic usages of the Web API. However, you are free to write your own implementation of the HttpMessageHandler. This might be useful if you want to perform a uniform task for every request or response that comes through, such as adding a security key to the header or examining incoming responses for a correct format.

You must use caution when adding custom code to your HttpMessageHandler on the client-side, however. The idea behind a Web API service is that the functionality can be called by a wide variety of clients. Putting too much logic about the transaction on the client-side may require replicating that code on every client that uses the service. This is something that you should generally avoid, or at the very least, clients should have other ways to provide that information to the service other than requiring a custom HttpMessageHandler on the client-side.


ldn-pledgerwoodThis post is an excerpt from the online courseware for our
ASP.NET Web API HTTP Pipeline course written by expert Philip Ledgerwood.

Philip Ledgerwood has been a software developer for fifteen years. He currently works primarily in .NET technologies producing custom software for organizations of all sizes. He has also done extensive training for those same organizations in both technical and business process topics.

ASP.NET Web API’s: Default Mapping

Web API Routing

If you have used the MVC pattern in your web applications, you are already familiar with the concept of URL routing. The ASP.NET MVC framework, for instance, knows which controller action to call by looking at pieces of the URL and using those pieces to identify the controller and the controller action.

Web API routing works in a similar way, except that the action is not specified in the URL. Instead, the action is selected based on the HTTP method used in the request.

Default Mapping

Like the ASP.NET MVC framework, you can find the default routing table for the Web API in Global.asax.

Contrast this with the default routing table for ASP.NET MVC controllers:

The differences in the properties that are set and the URL mapping pattern may seem subtle, but they are important. Not only do the two mapping schemes they also capture the primary differences between a RESTful API and something that maps to method names in a URL.

The first difference is the MapHttpRoute method. This method is used to map API routes as opposed to the MapRoute method, which is used for ASP.NET MVC routing tables.

The second difference is that “api” is a hard-coded value in the Web API map for URLs. This prevents mapping conflicts with the ASP.NET MVC framework. It’s quite possible for both your MVC controllers and your Web API controllers to have the same names, so having “api” as part of all Web API URLs makes sure your routing table uses the right controller for a request.

The third difference is that the routeTemplate does not have an action parameter like the ASP.NET MVC framework routes do. In ASP.NET MVC, the URL specifies the action that should be called. In the Web API, the API decides which action should be called based on the HTTP method handled bythe controller.

In order to map a request to a controller action, Web API routing goes through the following steps:

  1. Checks for an “api” in the beginning. If there isn’t one, it is handled by MVC routing, instead.
  2. Adds the word “Controller” to the value found in the {controller} parameter of the URL and uses this to find the appropriate Web API controller
  3. Looks for an action with a name that begins with the HTTP method used in the request. For instance, if a GET method is used, Web API will look for an action name that starts with the word “Get,” a POST method willtrigger an action that starts with the word “Post,” and so on.
  4. Maps any additional parameters to action parameters.

Table 1 shows how the HTTP method and the URL pattern will map to actions by default. Once again, remember that the action name only has to begin with the HTTP method name; everything else is irrelevant and can be whatever you want.

HTTP Method URL Matching Action
GET api/books GetAllBooks()
GET api/books/2 GetBook(int id)
POST api/books PostNewBook()
PUT api/books/2 DeleteBook(int id)
DELETE api/books/2 DeleteBook(int id)

Table 1. Example HTTP requests mapping to controller actions.

This post is an excerpt from the online courseware for our ASP.NET Web API Basics course written by expert Philip Ledgerwood.

ldn-pledgerwoodPhilip Ledgerwood has been a software developer for fifteen years. He currently works primarily in .NET technologies producing custom software for organizations of all sizes. He has also done extensive training for those same organizations in both technical and business process topics.