HTTP Methods and Routing

In routing with ASP.NET Web API, the HTTP methods that the incoming request is made through, virtually invisible at first glance, play a huge role in the selection of controller actions. Routing in ASP.NET Web API is inspired by ASP.NET MVC routing, but there is one missing part inside the example in Listing 8-3: the action route parameter. For those not familiar with ASP.NET MVC, the action parameter represents the ASP.NET MVC controller action method name and the action method inside the controller is selected on the basis of this parameter’s value. In ASP.NET Web API, the actions selected depend upon the HTTP method the request is made through.

For example, there is a sample controller named CarsController, as shown in Listing 8-5.

Listing 8-5.  Sample CarsController

public class CarsController : ApiController {

    public string[] Get() {

        return new string[] {

            "Car 1",
            "Car 2",
            "Car 3",
            "Car 4"
        };
    }
    public string Get(int id) {

        return string.Format("Car {0}", id);
    }

    public string[] GetCarsByType(string type) {

        return new string[] {

            "Car 2",
            "Car 4"
        };
    }
    public string[] GetCarsByMake(string make) {

        return new string[] {
            "Car 1",
            "Car 3",
            "Car 4"
        };
    }
    public string[] GetCarsByMakeByType(
        string make, string type) {

        return new string[] {
            "Car 4"
        };
    }
}

With the route registered in Listing 8-3, the first CarsController.Get method in Listing 8-5 will be invoked when there is a GET request to the /api/cars URL. Let’s quickly go through the steps to understand how the Get method of CarsController is invoked.

The “api” part inside the URL is the static URL segment that was specified inside the route template. The second segment inside the URL is “cars”. Because it was indicated inside the route template that the second segment would be the controller name, the system will look for a unique class that implements the IHttpController interface and has a prefix of “cars” (case insensitive) and “Controller” (again case insensitive), as concatenated on the prefix (CarsController). This action is performed by the registered implementation of the IHttpControllerSelector interface, which is the DefaultHttpControllerSelector class by default and the controller selector instance here is invoked by HttpControllerDispatcher. If any controller is found, the request goes up one level inside the pipeline. If no controller is found, the HttpControllerDispatcher sets up the “404 Not Found” response message and terminates the request. The example here has a controller named CarsController and this means that the request will be dispatched to a higher level inside the pipeline, where the execution of the ExecuteAsync method of the controller instance happens.

In the example, when the ExecuteAsync method of the ApiController class is executed, the action method selection logic kicks in. (The details of how this logic is performed mostly belong to Chapter 9, where this will be covered in depth.) What you need to know here to make sense out of the current scenario is that the action method selection occurs on the basis of the HTTP method chosen. For example, here a GET request is being made to the api/cars URL, and it is dispatched to CarsController. As the request is made through the HTTP GET method, the controller will look for a method with a prefix of “Get” (case insensitive).

One question that may pop up right now might concern having two Get methods inside CarsController. As one of the Get methods accepts the parameter id and the request doesn’t contain an id value (such as a route or a query string value), the system will select the method with no parameters. Trying to make a GET request to the URL api/cars/1 will invoke the second Get method because the third URL segment inside the route template represents the id value. This value is an optional parameter because its default value was defined as System.Web.Http.RouteParameter.Optional. Table 8-1 shows a list of request URLs and HTTP methods and their corresponding action methods.

This behavior is the same for other verbs as well (as indicated earlier, it will be explored in depth in Chapter 9). Another option with routing—also known as RPC, or Remote Procedure Call—enables the direct calling of an action method, for example, by issuing a GET request to /api/cars/ExpensiveCars and invoking the ExpensiveCars method inside the CarsController. This behavior mostly relates to the controller part of the framework, so it too will be thoroughly explored in Chapter 9.

Having Multiple Web API Routes

Depending on your needs, you might want to have multiple Web API routes in your application. This is a totally acceptable option in ASP.NET Web API, but there are a few important things to be aware of.

If you have multiple routes, the registration order of the routes matters. When a request comes to the routing level, the route collection is scanned to find a match. As soon as a match is found, the search stops, and the remaining routes get ignored. The first route registered will be looked at first, and so on. Let’s see the example in Listing 8-6.

Listing 8-6.  Multiple Routes Sample

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}",
        new { id = RouteParameter.Optional }
    );
    routes.MapHttpRoute(
        "VehicleHttpRoute",
        "api/{vehicletype}/{controller}",
        defaults: new { },
        constraints: new { controller = "^vehicles$" }
    );
}

The first route is the route that has been used so far in this chapter, and the second one is a little different. Notice that a constraint was used for the controller parameter (don’t worry, constraints will be explained later in this chapter). With this constraint in place, we are indicating the routing mechanism to match only if the controller parameter is “vehicles”. To complete the sample, there are also two controllers: CarsController (Listing 8-7) and VehiclesController (Listing 8-8).

Listing 8-7.  CarsController

public class CarsController : ApiController {

    public string[] Get() {

        return new string[] {
            "Car 1",
            "Car 2",
            "Car 3"
        };
    }
}

Listing 8-8.  VehiclesController

public class VehiclesController : ApiController {

    public string[] Get(string vehicletype) {

        return new string[] {
            string.Format("Vehicle 1 ({0})", vehicletype),
            string.Format("Vehicle 2 ({0})", vehicletype),
            string.Format("Vehicle 3 ({0})", vehicletype),
        };
    }
}

In this case, if a request is sent against /api/SUV/vehicles to invoke the action method inside VehiclesController, the second route will never be hit because the first one will be a match and “SUV” will be the value of the controller parameter for the first route template. So the response will be a “404 Not Found”, as shown in Figure 8-1.

If the routes are registered as Listing 8-9 shows, you will get the exact behavior desired here (Figure 8-2).

Listing 8-9.  Multiple Routes Correct Sample

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "VehicleHttpRoute",
        "api/{vehicletype}/{controller}",
        defaults: new { },
        constraints: new { controller = "^vehicles$" }
    );

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}",
        new { id = RouteParameter.Optional }
    );

}

Route Defaults

For a route to match a request, the first requirement is to supply all the parameter values. For example, if the route template consists of three parameters and only two of them are supplied, the route will be ignored unless the ignored parameters have a default value specified.

The route parameters can have default values and having them enables you to omit specifying parameters. Listing 8-10 shows a slightly different route from the one already used a lot in this chapter.

Listing 8-10.  A Route Sample

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}"
    );
}

A look at the route template will show that the URL for this route consists of three segments. The first one is the static value, and the remaining two are the parameters that can be changed. When a request is sent to /api/cars/15, this route will be a match, and the request will get inside the ASP.NET Web API pipeline. Omit the id parameter and send a request against /api/cars, however, and this route will never be a match.

There are two solutions to this issue.

• Specify another route, one that will be a match for the request.
• Provide a default value for the id parameter to omit the id segment inside the URL.

Let’s take the second approach to solve the issue here. In order to provide default values for the parameters, let’s provide an anonymous object for the default parameter of the MapHttpRoute extension method. The property names of the anonymous object should be the same as the parameter names. If a property name provided doesn’t have a match among the route parameters, then that property will get ignored. Listing 8-11 is an example of a solution to the problem.

Listing 8-11.  A Route Sample with Default Values

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}",
        new { id = string.Empty }
    );
}

When a request is now sent to /api/cars, this route will be a match, and the value of the id route parameter will be String.Empty, which is equivalent to “ ”. If a value is provided for the id segment, the default value will be overridden by the one provided. For example, if a request is sent to /api/cars/15, the value of the id route parameter will be 15.

Optional Parameters

What is actually wanted in the above example is, not a default value for the id parameter, but an optional parameter. In the Web API framework, provide the Optional static property of the System.Web.Http.RouteParameter for a route parameter as the default value, and the route parameter will be omitted. Listing 8-12 is an example of this feature.

Listing 8-12.  A Route with Optional Parameters

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}",
        new { id = RouteParameter.Optional }
    );
}

When a request is sent to /api/cars, the route in Listing 8-12 will still be a match, but this time there will be no id parameter specified. Instead, the id parameter will be omitted.

Route Constraints

In some cases, you won’t want a particular URL structure to match a route. In such cases, the route constraint feature allows you to restrict the requests that match a particular route. A route constraint can be applied to each route parameter and in order to specify a constraint for a route parameter, you will need to provide an anonymous object for the constraints parameter of the MapHttpRoute extension method. The property names of the anonymous object provided should be the same as the parameter names.

The route constraints can be applied either as regular expressions or as custom route constraints, and these options will be explained separately.

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { },
        constraints: new { id = @"d + " }
    );
}

public class OptionalRegExConstraint : IHttpRouteConstraint {

    private readonly string _regEx;

    public OptionalRegExConstraint(string expression) {

        if (string.IsNullOrEmpty(expression)) {

            throw new ArgumentNullException("expression");
        }
        _regEx = expression;
    }

    public bool Match(
        HttpRequestMessage request,
        IHttpRoute route,
        string parameterName,
        IDictionary <string, object> values,
        HttpRouteDirection routeDirection) {

        if (values[parameterName] != RouteParameter.Optional) {

            object value;
            values.TryGetValue(parameterName, out value);
            string pattern = "^(" + _regEx + ")$";
            string input = Convert.ToString(
                value, CultureInfo.InvariantCulture);

            return Regex.IsMatch(
                input,
                pattern,
                RegexOptions.IgnoreCase |
                RegexOptions.CultureInvariant);
        }

        return true;
    }
}

protected void Application_Start(object sender, EventArgs e) {

    var routes = GlobalConfiguration.Configuration.Routes;

    routes.MapHttpRoute(
        "DefaultHttpRoute",
        "api/{controller}/{id}",
        new { id = RouteParameter.Optional },
        new { id = new OptionalRegExConstraint(@"d + ") }
    );
}