How Routing Works In ASP.NET WEB API

Introduction

This article will explain us how a Web API's action method is invoked from the request. That means how the respective action is performed.

Requirements

• Visual Studio 2012 or above.

Routing

The dictionary definition of Route is 'the path taken to reach the destination'. Similarly routing in ASP.NET Web API is the mechanism to reach the destination. The destination is the exact action method which is to be invoked based on API's Request.



Source: wikipedia.org

If you have little knowledge on ASP.NET MVC's Routing, you will simply understand the Routing concept in Web API. Both are same but the only difference is Web API selects the action method based on the HTTP method, whereas in MVC URI path is used to find out the respective action method.

To understand the Web API's Routing I am creating a simple Web API application.



Once the project is created, we can find the WebAPIConfig.cs file under App_Start folder. This file consists all the routes of the application.



The WebAPIConfig.cs will be created along with default route in the application.



If we observe the above code, we can find three parts of the Web API's route. They are.. name of the Route, Route Template and Defaults of Route template.

The key of the routing is Route Template. This will show where to go if the requested URI is of this type. The parameters which are in the curly braces will be replaced by the URI values, but the structure of the requested URI has to be matched with the route template, then only the route search for the respective action method.

In routing concepts there are three phases to reach the destination. That means invoking exact action method. They are:

• Finding the exact Route Template
• Finding the Controller
• Finding the Action Method

1. Finding the exact Route Template

Definition: Route Template is simply a URI which consists of placeholders.

Example: "API/{controller}/{id}"

The above example looks like a URL but it is having placeholders called controller and id. These placeholders are kept within curly braces.

Note:

• Route Template can also have literals, like "API/Demo/{controller}/{id}". Here Demo is the literal.
• Placeholder's value can be given in the defaults of the Route. Like defaults: new { Controller="Student" }.

Explanation

Route Template acts as an entry point of the Routing in ASP.NET WEB API. Because, if the given or requested URI is matched with the Route Template then only the API looks for the controller and action method.

When Request has come to the API, first of all it tries to match the URI with one of the Route Templates. If the template has literals, then API checks for exact match of characters. For the placeholders it does not verify the exact value. In the above example Route Template has 'Demo' literal. So that API checks the same literal in the Route Template.

Note:

• API does not check URI's host name.
• API selects the first route which is matched with route template.
• If the placeholder's value is given in default of the Route, then the URI will not have the value for that placeholder.

Example: URI: http://localhost/API/Demo/1

This URI match with the above mentioned Route Template as Controller placeholder value has already given in the default of the Route.

Once the Requested URI is matched with Route Template, placeholder's values are stored as the KeyPair Values in Route Dictionary. Keys are the placeholders and these Values are taken from the URI.

Route Dictionary values based on the above Route Template are Controller:Stdent and id:1.

Note: Route Dictionary will have the values for placeholders only.

2. Finding the Controller

Finding the controller is simple. The API or Framework will get the Controller name from the Controller KeyValue of the Route Dictionary. From the above example Controller value is Student. This value is been taken as Controller key has Student value. Now, the framework appends Controller string to the KeyValue and Search for that controller. i.e StudentController. If there is no match for this controller then API returns error message.

3. Finding the Action Method

This is a little typical phase of Routing. For me it took much time to write this phase. To find the exact action method, framework gets the three values. They are:

• The Http Method of the Request.
• Action placeholder value from the route dictionary.
• Parameters of the actions.

Here Http Method plays an important role in selecting the exact action method. This is what we discussed in the beginning. (Action methods are selected based on the Web API 's Http method.)

Now, important aspect is that the Action methods are selected based on the Naming Convention of Http method or Attribute placed with Http Method above it.

Explanation:

• If the requested action method is of type HttpGet, either Action name would be Get or it should start with Get___.
  
  Example: GetStudent() or GetStudentDetails() actions will be selected.
  
  
• The Action method selection will be made on the attribute as well.
  

  [HttpGet]
  public HttpResponseMessage GiveMeStudent()
  {
     //To Do
  }

Note:

• The action methods which are of type public and are inherited by the APIController class are selected. If the method is private or not inherited by the APIController, framework returns an error.
  
  
• If the Action Method not satisfied with naming convention or Attribute is not placed above the method, by default the framework treats the action method as HttpPost method. (In case the Controller have specified action name which matches the exact action key value of Route Dictionary.).

The final one is Parameter Binding. If the parameter of simple type API gets the value from URI if it is of complex type such as entity, framework serializes the entity and bind it with parameter of the action method.

Summary

In this article we have discussed how the Web API's request takes right path to respective action method. Here we have discussed only theoretical part of the Routing. In my next article we will discuss routing with a real world example.