LearnNowOnline

Blog

ASP.NET Web API's: Default Mapping

Excerpt by Phil Ledgerwood | February 21, 2013

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.

routes.MapHttpRoute(

name: "DefaultApi",

routeTemplate: "api/{controller}/{id}",

defaults: new { id = RouteParameter.Optional }

);

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

routes.MapRoute(

name: "Default",

url: "{controller}/{action}/{id}",

defaults: new { controller = "Home", action = "Index",

id = UrlParameter.Optional }

);

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.

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.