Your First Controller Derived From ApiController

Let’s try to implement a controller that holds the same logic as Listing 9-3 but uses ApiController as the base class this time. Listing 9-4 shows how it is implemented.

Listing 9-4.  CarsController with ApiController

public class CarsController : ApiController {

    public string[] Get() {

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

When we send a GET request to /api/cars, we get the same result as in Listing 9-3 but obviously with a very clean programming model. Inside our CarsController in Listing 9-4, we didn’t perform an HTTP method check, and we are returning just the object we care about. When a request comes to this CarsController controller class, the action selection logic is performed, at which we will look closely in the “Action Selection” section farther along in this chapter. The default convention here is that the action name should be the same name as the HTTP method name through which the request was made or with which it starts such as “GetCars.” The lookup here is case insensitive.

Before moving forward, let’s get to know the members of the ApiController abstract class first.

ApiController Members

ApiController exposes some properties and provides some methods that make it easy to work with the request. This subsection will list and explain those properties and methods. Table 9-2 lists public properties of the ApiController class.

Besides the properties listed in Table 9-2, there are three different public virtual methods of the ApiController class, as Listing 9-5 shows.

Listing 9-5.  ApiController Public Methods

public abstract class ApiController : IHttpController, IDisposable {
     
    //Lines omitted for brevity
   
    protected virtual void Dispose(bool disposing);
     
    public virtual Task<HttpResponseMessage> ExecuteAsync(
        HttpControllerContext controllerContext, CancellationToken cancellationToken);
         
    protected virtual void Initialize(HttpControllerContext controllerContext);
}

The Initialize method sets up the proper public properties before the ExecuteAsync method logic is executed.

HTTP Method–Based Routing

HTTP method–based routing looks for the method names inside the controller and filters out the ones that have the exact name of the HTTP method or the prefix that equals the HTTP method name. This comparison is case insensitive.

Since we’ve been working with this approach in this section so far, we are familiar with it, but our car gallery API application has a problem we haven’t found a solution for. We need to find two methods that will process the GET requests such that one of them will return a single car value based on the car’s id. The ApiControllerActionSelector has a way of selecting the actions on the basis of their parameters. For example, if we have another Get method inside the CarsController, one that accepts a parameter named id, and the request contains either a route or a query string value named id, this Get method will be selected as the appropriate action method and invoked. Now, let’s see this in action. Listing 9-13 shows the implementation of this second Get method.

Listing 9-13.  CarsController with a Second Get Action

public class CarsController : ApiController {

    private readonly CarsContext _carsCtx =
        new CarsContext();
     
    //Lines omitted for brevity

    public Car GetCar(int id) {

        var carTuple = _carsCtx.GetSingle(id);

        if (!carTuple.Item1) {

            var response =
                Request.CreateResponse(HttpStatusCode.NotFound);
                 
            throw new HttpResponseException(response);
        }

        return carTuple.Item2;
    }
}

When we send a request against /api/cars/1 (Figure 9-7), we’ll be invoking the action method shown in Listing 9-13.

Also, we can get the same result by sending a request against /api/cars?id=1 (Figure 9-8).

Until this point, we’ve been telling you that the action method name needs to have the exact name of the HTTP method or the prefix that is the same as the HTTP method name. This is one way to proceed with the HTTP method–based routing. The other way is to provide an action HTTP method provider attribute for the action method.

public class CarsController : ApiController {

    [HttpGet]
    public string[] Cars() {

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

Action-Based Routing

Besides the HTTP method–based routing, there is also another routing feature that markedly affects the default action selection logic. If there is a route parameter named action for the chosen route, this parameter will look up the proper action. When using action-based routing, the HTTP method provider attribute needs to be set explicitly. Otherwise, the action method will never be selected.

Listing 9-15 shows a sample route definition that contains a parameter named action.

Listing 9-15.  A Route for So-Called Action-Based Routing

protected void Application_Start(object sender, EventArgs e) {

    var config = GlobalConfiguration.Configuration;
    var routes = config.Routes;

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

There is also the CarsController class, which contains an action method named List (Listing 9-16).

Listing 9-16.  CarsController with an Action Named List

public class CarsController : ApiController {

    [HttpGet]
    public string[] List() {

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

When you make a request against /api/cars/list, you should get the cars list, as expected (Figure 9-10).

Action Method Selectors and NonActionAttribute

An action method selector is a .NET attribute that implements the IActionMethodSelector interface and allows interference in the action method selection process. The IActionMethodSelector is an internal interface. There is only one implementation of this interface: the NonActionAttribute.

When you have a defined public method in your Web API controller and don’t want it treated as a controller action method, you can apply the NonActionAttribute to that method. It won’t then be available as an action method.

Listing 9-17 shows an example for this feature.

Listing 9-17.  NonActionAttribute Usage Sample

public class CarsController : ApiController {

    public string[] Get() {

        return GetCars();
    }

    [NonAction]
    public string[] GetCars() {

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

We are using the default route for this example. If we make a GET request against /api/cars and don’t use the NonActionAttribute for the GetCars method, we should get an HTTP 500 response, indicating that multiple actions were found that match the request. If the NonActionAttribute is applied to the GetCars method, the GetCars method will not be treated as an action method anymore.

Returning an Object

The most common occurrence is to return an object as a result. When an object instance is returned, the return value will be processed by the proper formatter according to the content negotiation process. Then the processed return value will be sent to the client, along with the response message. All these operations are done out of the box.

For instance, in nearly all of our examples so far, we’ve been returning a string[] object. We’ve seen that the response message carries the content in the proper format. Let’s look at the example in Listing 9-18.

Listing 9-18.  Returning string[] Object Inside an Action Method

public class CarsController : ApiController {

    public string[] Get() {

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

When we make a GET request against /api/cars, we’ll get the response message, along with the cars list in the proper format (Figure 9-11). The format differs on the basis of the request, the registered formatters, and the registered content negotiation service. (Chapter 12 is entirely dedicated to formatters and content negotiation. We’ll see there how it matters.)

Except for the message body, we don’t at the moment have any control over the returned response message inside the controller action, but we can solve this problem by explicitly creating and returning an HttpResponseMessage instance. Let’s talk about that next.

Returning a Response Message

When returning an instance of HttpResponseMessage, you have explicit control over the response message to be sent to the client. We can define the response headers and response status code in the case of HttpResponseMessage. Listing 9-19 shows an example of this procedure, with an action method for an HTTP DELETE request.

Listing 9-19.  DeleteCar Controller Action That Returns an HttpResponseMessage Instance

public class CarsController : ApiController {

    public HttpResponseMessage DeleteCar(int id) {

        //Check here if the resource exists
        if (id != 1) {

            return new HttpResponseMessage(HttpStatusCode.NotFound);
        }

        //Delete the car object here

        var response = new HttpResponseMessage(HttpStatusCode.OK);
        return response;
    }
}

As usual with an HTTP DELETE request, the controller action first checks whether the resource exists according to the passed-in id parameter. If the resource exists, it deletes the associated object and returns a “200 OK” response (Figure 9-12). We’re able to set the status code here because we’re returning an HttpResponseMessage instance. We might go farther and alter the response headers as well if we want.

However, we might need to send a properly formatted object inside the response message body and alter the response message at the same time. As we learned in Chapter 4, HttpResponseMessage has a property named Content, which is a type of the abstract HttpContent class. We can pass the object we want here. Listing 9-20 shows an example for an action method that handles HTTP GET requests to return a list of cars.

Listing 9-20.  PostCar Controller Action That Returns an HttpResponseMessage Instance with an Object

public class CarsController : ApiController {

    public HttpResponseMessage GetCars() {

        var cars = new string[] {
            "Car 1",
            "Car 2",
            "Car 3"
        };

        HttpResponseMessage response =
            Request.CreateResponse<string[]>(HttpStatusCode.OK, cars);
        response.Headers.Add("X-Foo", "Bar");
        return response;
    }
}

What we’re returning here is an instance of HttpResponseMessage. We have a list of cars that we want to return as well. Also, we want to be able to handle the content negotiation automatically. All of our requirements can be fulfilled by the CreateResponse extension method for HttpRequestMessage class. Finally, we added a custom header to demonstrate that we have full control over the response.

When we make a GET request against /api/cars, we should get back a list of cars in a proper format and the custom response header we’ve set, too (Figure 9-13).

Also, notice that we want the response message in XML format, and the server gives us what we want.

Throwing HTTP Exceptions (HttpResponseException)

When an exception is thrown inside an action, the exception filters will be invoked to handle it (more about this in Chapter 11). If there is no exception filter or an exception filter didn’t handle the exception, eventually the HttpControllerDispatcher will handle it and send back a proper HttpResponseMessage instance.

However, if the exception is a type of HttpResponseException, the exception will be handled by the ApiControllerActionInvoker immediately. The exception filters won’t be invoked. This gives you the ability to stop processing immediately and return with a proper HTTP status code. Also, if you want to terminate the request inside a controller action and if the return expression type is not HttpResponseMessage, you can throw HttpResponseException to stop the processing of the action method.

Listing 9-21 is an example of throwing HttpResponseException inside a controller action.

Listing 9-21.  A Sample Controller Action That Throws HttpResponseException

public class CarsController : ApiController {

    public string[] GetCars() {

        //stop processing and throw the HttpResponseException
        var response = new HttpResponseMessage(HttpStatusCode.BadRequest);
        throw new HttpResponseException(response);
    }
}

The return type of the action method is string[]. Note that we are still able to alter the response message. When we send a GET request against /api/cars, we will get a “400 Bad Request” response (Figure 9-14).

Returning Error Responses

The ASP.NET Web API framework has a built-in mechanism to handle errors efficiently and send user-friendly error messages to the consumer. This built-in error-handling mechanism also works well with validation and several other components of the framework, as will be seen in Chapter 13.

When an unhandled exception occurs at the controller level and the exception handler doesn’t set any specific response message, the exception details are sent inside the message body with the “500 Internal Server Error” status code. Assuming the presence of the controller shown in Listing 9-22, the GetCars method will throw a DivideByZeroException.

Listing 9-22.  The CarsController Class

public class CarsController : ApiController {

    public string[] GetCars() {

        int left = 10,
            right = 0;

        var result = left / right;

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

When a request is sent to /api/cars, the response message body will carry the exception details (see Figure 9-15).

If the request is sent by indicating acceptance of the XML format, the response body will be in XML format. Note, too, that this sample is being run locally; that is why you see the exception details. As Chapter 1’s “Configuration” section shows, the IncludeErrorDetailPolicy is set by default to IncludeErrorDetailPolicy.LocalOnly, and the framework honors that setting here. Change this setting to Never, as shown in Listing 9-23, and you won’t see the exception details (see Figure 9-16).

Listing 9-23.  IncludeErrorDetailPolicy Set to Never

protected void Application_Start(object sender, EventArgs e) {

    var config = GlobalConfiguration.Configuration;

    //Lines omitted for brevity...

    config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Never;

}

What you see here is the HttpError class in play. When an exception occurs inside a controller action, an instance of an HttpError is serialized to the wire by the proper formatter. The HttpError message is just a Dictionary<string, object> object that provides some helper methods for creating errors that contain error messages, exceptions, or invalid model states.

The HttpError class has four constructors, which accept parameters to create over the existing error stacks a new HttpError message, such as an Exception instance of a ModelStateDictionary instance. Listing 9-24 shows the signature of the HttpError class.

Listing 9-24.  The Signature of the HttpError Class

[XmlRoot("Error")]
public sealed class HttpError : Dictionary<string, object>, IXmlSerializable {

    public HttpError();
    public HttpError(string message);
    public HttpError(Exception exception, bool includeErrorDetail);
    public HttpError(ModelStateDictionary modelState, bool includeErrorDetail);

    public string Message { get; set; }
}

If the framework didn’t provide such a feature to return an exception message by default, the same result could be achieved via the process shown in Listing 9-25.

Listing 9-25.  GetCars Action Method

public string[] GetCars() {

    try {

        int left = 10,
            right = 0;

        var result = left / right;

    }
    catch (DivideByZeroException ex) {

        var faultedResponse = Request.CreateResponse(
            HttpStatusCode.InternalServerError,
            new HttpError(ex, includeErrorDetail: true));

        throw new HttpResponseException(faultedResponse);
    }

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

A request now sent to /api/cars will generate the same result, shown in Figure 9-17, already seen in Figure 9-15.

Actually, the solution Listing 9-25 provides doesn’t behave quite the same as the built-in default solution, because the includeErrorDetail parameter is directly set to true. This wouldn’t honor the IncludeErrorDetail configuration settings. Of course, the value of the IncludeErrorDetailPolicy property could be retrieved from the controller’s Configuration property, but there would then be a need to determine the cases where the error details had to be included and where they didn’t.

To be able to honor the IncludeErrorDetailPolicy settings and make it easy to return error responses, there is an extension method for HttpRequestMessage. Called CreateErrorResponse, it has several overloads, as Listing 9-26 shows.

Listing 9-26.  The CreateErrorResponse Extension Method for HttpRequestMessage and Its Overloads

public static class HttpRequestMessageExtensions {

    public static HttpResponseMessage CreateErrorResponse(
        this HttpRequestMessage request,
        HttpStatusCode statusCode, Exception exception);

    public static HttpResponseMessage CreateErrorResponse(
        this HttpRequestMessage request,
        HttpStatusCode statusCode, HttpError error);

    public static HttpResponseMessage CreateErrorResponse(
        this HttpRequestMessage request,
        HttpStatusCode statusCode, ModelStateDictionary modelState);

    public static HttpResponseMessage CreateErrorResponse(
        this HttpRequestMessage request,
        HttpStatusCode statusCode, string message);

    public static HttpResponseMessage CreateErrorResponse(
        this HttpRequestMessage request,
        HttpStatusCode statusCode, string message, Exception exception);
         
    //Other extension methods are omitted for brevity . . .
}

All overloads of the CreateErrorResponse extension method return an HttpResponseMessage instance. Just like the CreateResponse extension method, this extension method also runs the content negotiation behind the scenes to return the response in a proper format. The CreateErrorResponse can be used to create error responses anywhere inside the ASP.NET Web API pipeline, including message handlers, filters, and controllers.

Listing 9-27 shows the GetCars implementation by using the CreateErrorResponse method.

Listing 9-27.  GetCars Action Method

public string[] GetCars() {

    try {

        int left = 10,
            right = 0;

        var result = left / right;

    }
    catch (DivideByZeroException ex) {

        var faultedResponse = Request.CreateErrorResponse(
            HttpStatusCode.InternalServerError, ex);

        throw new HttpResponseException(faultedResponse);
    }

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

A request now sent to /api/cars will again generate the same result as the one in Figure 9-15 (also shown in Figure 9-18) and will also honor the IncludeErrorDetailPolicy configuration settings.

The HttpError class can also be used for arbitrary error messages. As Listing 9-28 shows, one of the overloads of the CreateErrorResponse extension method accepts the HttpError instance. It’s also possible to construct a new HttpError instance with custom error details and pass it into the CreateErrorResponse method.

The sample shown in Listing 9-28 demonstrates this usage. The GetCar controller action method accepts an integer for the id parameter, but we only allow even numbers. So if the number is odd, we will construct a new HttpError message, add the message for the error, and return a new HttpResponseMessage instance through the CreateErrorResponse extension method of the HttpRequestMessage.

Listing 9-28.  GetCar Action Method

public HttpResponseMessage GetCar(int id) {

    if ((id % 2) != 0) {

        var httpError = new HttpError();
        httpError.Add("id",
            "Only "even numbers" are accepted as id.");

        return Request.CreateErrorResponse(
            HttpStatusCode.InternalServerError,
            httpError);
    }

    return Request.CreateResponse(
        HttpStatusCode.OK,
        string.Format("Car {0}", id));
}

When a request is sent against /api/cars/1, a “500 Internal Server Error” response is returned, because the id parameter supplied is not an even number (see Figure 9-19).

What will mostly be leveraged is the CreateErrorResponse extension method along with the validation. Chapter 13 is dedicated solely to the validation topic, and there you’ll see samples showing how to efficiently use the CreateErrorResponse extension method to provide better validation error messages.