Working with ASP.NET Web API

(For more resources related to this topic, see here.)

The ASP.NET Web API is a framework that you can make use of to build web services that use HTTP as the protocol. You can use the ASP.NET Web API to return data based on the data requested by the client, that is, you can return JSON or XML as the format of the data.

Layers of an application

The ASP.NET Framework runs on top of the managed environment of the .NET Framework.

The Model, View, and Controller (MVC) architectural pattern is used to separate the concerns of an application to facilitate testing, ease the process of maintenance of the application’s code, and to provide better support for change. The model represents the application’s data and the business objects; the view is the presentation layer component, and the controller binds the model and the view together. The following figure illustrates the components of Model View Architecture:

The MVC Architecture

The ASP.NET Web API architecture

The ASP.NET Web API is a lightweight web-based architecture that uses HTTP as the application protocol. Routing in the ASP.NET Web API works a bit differently compared to the way it works in ASP.NET MVC. The basic difference between routing in MVC and routing in a Web API is that, Web API uses the HTTP method, and not the URI path, to select the action. The Web API Framework uses a routing table to determine which action is to be invoked for a particular request. You need to specify the routing parameters in the WebApiConfig.cs file that resides in the App_Start directory.

Here’s an example that shows how routing is configured:

routes.MapHttpRoute(
   name: "Packt API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

The following code snippet illustrates how routing is configured by action names:

routes.MapHttpRoute(
    name: "PacktActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

The ASP.NET Web API generates structured data such as JSON and XML as responses. It can route the incoming requests to the actions based on HTTP verbs and not only action names. Also, the ASP.NET Web API can be hosted outside of the ASP.NET runtime environment and the IIS Web Server context.

Routing in ASP.NET Web API

Routing in the ASP.NET Web API is very much the same as in the ASP.NET MVC. The ASP.NET Web API routes URLs to a controller. Then, the control is handed over to the action that corresponds to the HTTP verb of the request message. Note that the default route template for an ASP.NET Web API project is {controller}/{id}—here the {id} parameter is optional. Also, the ASP.NET Web API route templates may optionally include an {action} parameter. It should be noted that unlike the ASP.NET MVC, URLs in the ASP.NET Web API cannot contain complex types. It should also be noted that complex types must be present in the HTTP message body, and that there can be one, and only one, complex type in the HTTP message body.

Note that the ASP.NET MVC and the ASP.NET Web API are two distinctly separate frameworks which adhere to some common architectural patterns.

In the ASP.NET Web API framework, the controller handles all HTTP requests. The controller comprises a collection of action methods—an incoming request to the Web API framework, the request is routed to the appropriate action. Now, the framework uses a routing table to determine the action method to be invoked when a request is received.

Here is an example:

routes.MapHttpRoute(
    name: "Packt Web API",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Refer to the following UserController class.

public class UserController
<UserAuthentication>: BaseApiController<UserAuthentication>
{
    public void GetAllUsers() { }
    public IEnumerable<User> GetUserById(int id) { }
    public HttpResponseMessage DeleteUser(int id){ }
}

The following table illustrates the HTTP method and the corresponding URI, Actions, and so on:

The Web API Framework matches the segments in the URI path to the template. The following steps are performed:

1. The URI is matched to a route template.
2. The respective controller is selected.
3. The respective action is selected.

The IHttpControllerSelector.SelectController method selects the controller, takes an HttpRequestMessage instance and returns an HttpControllerDescriptor. After the controller has been selected, the Web API framework selects the action by invoking the IHttpActionSelector.SelectAction method. This method in turn accepts HttpControllerContext and returns HttpActionDescriptor. You can also explicitly specify the HTTP method for an action by decorating the action method using the HttpGet, HttpPut, HttpPost, or HttpDelete attributes. Here is an example:

public class UsersController : ApiController
{
    [HttpGet]
    public User FindUser(id) {}
}

You can also use the AcceptVerbs attribute to enable HTTP methods other than GET, PUT, POST, and DELETE. Here is an example:

public class UsersController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public User FindUser(id) { }
}

You can also define route by an action name. Here is an example:

routes.MapHttpRoute(
    name: "PacktActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

You can also override the action name by using the ActionName attribute. The following code snippet illustrates two actions: one that supports GET and the other that supports POST:

public class UsersController :
ApiController
{
    [HttpGet]
    [ActionName("Token")]
    public HttpResponseMessage GetToken(int userId);

    [HttpPost]
    [ActionName("Token")]
    public void AddNewToken(int userId);
}