ASP.NET Web API Routing

Back to: ASP.NET Web API Tutorials For Beginners and Professionals

ASP.NET Web API Routing

In this article, I am going to discuss ASP.NET Web API Routing with examples. Please read our previous article where we discussed Cross-Origin Resource Sharing in Web AP with examples. The Routing in Web API is one of the most important concepts that you need to understand. Once you understand this concept, then you can easily learn the internal architecture of the ASP.NET Web API pipeline. As part of this article, we are going to discuss the following pointers in detail.

1. What is Routing in Web API?
2. Understanding the Route Table.
3. How does the Web API Framework handle an incoming HTTP Request?

What is Routing in Web API?

The ASP.NET Web API Routing module is responsible for mapping the incoming HTTP requests to a particular controller action method. If you are familiar with the ASP.NET MVC application, then you can easily understand the Routing as it is very much similar to the ASP.NET MVC Routing.

The major difference between these two routing mechanisms is that the ASP.NET Web API uses the HTTP method, not the URI path, to select the action. You can also use ASP.NET MVC style routing in Web API which we will discuss in our upcoming articles. ASP.NET Web API Framework supports two types of routing. They are as follows

1. Convention-based Routing
2. Attribute Routing

Convention-Based Routing in ASP.NET Web API

In Convention-Based Routing, the ASP.NET Web API Framework uses route templates to determine which controller and action method to execute. At least one route template must be added to the route table in order to handle the incoming HTTP requests.

Understanding the Routing Table in ASP.NET Web API:

In the ASP.NET Web API application, a controller is a class that is inherited from ApiController abstract class and this controller class contains action methods that actually handle the incoming HTTP requests. The public methods of the controller class are called action methods or actions. When the ASP.NET Web API Framework receives an HTTP request, it routes that HTTP request to an action method of a controller.

To determine which action method to select or invoke for a particular HTTP request, the ASP.NET Web API Framework uses a Routing table. When we create an ASP.NET Web API application, by default, the Visual Studio creates a default route for our application as shown in the below image. The following route is defined in the WebApiConfig.cs file, which is present inside the App_Start folder.

In the above WebApiConfig.Register() method, config.MapHttpAttributeRoutes() enables us to use Attribute Routing in ASP.NET Web API that we will discuss in our upcoming article. The config.Routes is a Route table or route collection of type HttpRouteCollection. The “DefaultApi” route is added in the route table using MapHttpRoute() extension method. The MapHttpRoute() extension method internally creates a new instance of IHttpRoute and adds it to an HttpRouteCollection. However, you can create a new route and add it into a collection manually and that we will discuss in our next article.

The Routing table in the ASP.NET Web API application contains each and every route template that we define in the WebApiConfig file. The default route template for the ASP.NET Web API application is “api/{controller}/{id}“. In this template, the term “api” is a literal path segment, and the {controller} and {id} are placeholder variables that will be replaced with the actual value.

When the Route Table is Created in the ASP.NET Web API Application?

The Route table is created only once during the application start. As we know, the Application_Start() event of the Global.asax file is the first method that is going to be executed when our application starts. So, from this method, it will call the Register static method of the WebApiConfig class which will fill the Route table with the defined routes for your application. Now, open the Global.asax file and you will find the following code in it. The point that you need to remember is, the things that you want to configure at the application level at the application startup, you need to configure within the Application_Start() event of the Global.asax file.

How does the ASP.NET Web API Framework handle an incoming HTTP Request?

When the ASP.NET Web API Framework receives an HTTP request, it tries to match the URI (Incoimg HTTP Request URL) against one of the route templates available in the routing table. If no route template matches the URI, then Web API Framework returns a 404 error to the client who actually makes the request. For example, the following URIs match with the default route template

However, the following URI does not match, because it lacks the “api” segment:
/products/1

The reason for using “api” in the route is to avoid collisions between the ASP.NET Web API and MVC routing. So, you can have “/products” go to the MVC controller, and “/api/products” go to the Web API controller. Of course, if you don’t like this convention, you can change the default route table that also we will discuss in our upcoming article.

Once a matching route is found in the Route table. The Web API Framework then selects the controller and the action. To select the controller, the Web API Framework adds “Controller” to the value of the {controller} variable that it received in the URI. To find the action, the Web API Framework looks at the HTTP method of the incoming request (i.e. GET, POST, PUT, or DELETE) and then looks for an action method whose name begins with that HTTP method name or method that decorates with the HTTP verb attributes.

For example, with a GET request, the Web API Framework looks for an action method that should start with “Get“, such as “GetProduct” or “GetAllProducts” and the methods that should decorate the GET HTTP verb. This convention only applies to GET, POST, PUT, and DELETE methods. You can enable other HTTP methods by using attributes on your controller that we will discuss in our upcoming article. Other placeholder variables in the route template, such as {id}, are mapped to action method parameters.

Example: Routing in ASP.NET Web API Application

Let us see an example for a better understanding of Web API Routing. Suppose you define the following Student controller in your application.

Here are some possible HTTP requests, along with the action that gets invoked for each request.

Notice that the {id} segment of the URI, if present, is mapped to the id parameter of the action. In our example, the  Student controller defines two GET methods, one with an id parameter and one with no parameter. It also defines one PUT method which takes one parameter of student type from the request body. Here another point you need to understand is that the POST request will fail as the controller does not have any “Post” method. 

In the next article, I am going to discuss the Routing variations in ASP.NET Web API Application with examples. Here, in this article, I try to explain Routing in ASP.NET Web API Application with examples. I hope you enjoy this Web API Routing article. 

Dot Net Tutorials

About the Author: Pranaya Rout

Pranaya Rout has published more than 3,000 articles in his 11-year career. Pranaya Rout has very good experience with Microsoft Technologies, Including C#, VB, ASP.NET MVC, ASP.NET Web API, EF, EF Core, ADO.NET, LINQ, SQL Server, MYSQL, Oracle, ASP.NET Core, Cloud Computing, Microservices, Design Patterns and still learning new technologies.