ASP.NET Web API allows you to easily build RESTful services that embrace the HTTP protocol (in opposition to SOAP and WCF). It’s main advantages are being lightweight and highly interoperable.
You can start using ASP.NET Web API by creating a new web project or installing the self hosted version of Web API via NuGet. Conceptually, it is very similar to ASP.NET MVC but instead of producing HTML views it can produce any media type. Web API can run anywhere, you can run it on IIS or self-hosted.
Routing in Web API
Like ASP.NET MVC, Web API uses controllers to handle web requests. In the case of Web API all our controllers will inherit from
ApiController and will contain a series of Action(HTTP) methods: Get, Post, Put, Delete that will reflect the HTTP verbs. The routing will work a little bit differently to ASP.NET MVC, in the sense that, the HTTP verb used when sending and HTTP request to our service will be used to route that request to the corresponding method in the controller.
RouteConfig for an ASP.NET MVC 4 project with Web API will contain the bits of code below:
1 2 3 4 5 6 7
Web API uses convention over configuration when looking for the right method to route your web request to. For instance, in the case of a
GET request, Web API will look for a method that starts with
Get and matches the expected signature (
If you are hosting Web API in IIS, you will need to allow for other HTTP verbs than GET and POST. Verbs such as DELETE, PUT, PATCH, etc are disabled by default.
A core concept of HTTP and the Web is content negotiation. Content negotiation consists on a negotiation between client and server to request/serve an specific representation of a resource.
For instance, image that your RESTful API provides access to employee resources and may support different representations of these resources such as images, json, xml, etc. When doing a request an image representation for the resource identified by this URL:
api/employees/3 a client will use the HTTP
Accept header to specify the MIME type
image/png. The server will then be able to serve that image representation for that particular employee.
Web API allows you to manage content negotiation via formatters. You can access the supported formatters via the
GlobalConfiguration.Configuration.Formatters in any
ApiController. The job of these formatters is to take any object and parse it into a representation in a particular media type. For instance, the
JsonMediaTypeFormatter creates a JSON representation of your objects. If the client request a media type that it is not supported by the server, the server will return a default representation, like JSON.
Parameter binding in Web API is a little bit different than the one we are used to in ASP.NET MVC. We have seen that content negotiation and formatters impact how data is returned to the client, there’s no
JSONResult, but parameter binding also differs when binding data as arguments to the action methods.
- Primitive types: By default they will be bound from the request URL and not from the body. If we want to bind from the body of the request we will need to explicitely specify it with the attribute
1 2 3 4
- Complex Types: They are assumed to be in the message body. Only a single model is allowed to be bound from the message body.
Resolving API urls in Razor
In order to resolve API urls from razor you can use the
Url.RouteUrl helper method:
Sending HTTP Responses to the Client
In order to send HTTP responses to the client Web API provides the
HttpResponseMessage type and the
Request.CreateResponse helper method to craft http responses:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Another option when sending error responses to the client is to throw a
HttpResponseException exception that also provides functionality for manipulating the HTTP response:
1 2 3 4 5 6 7
Testing Web API Services
1 2 3 4 5 6 7 8 9 10
Consuming an ASP.NET MVC Web API
ASP.NET Web API also ships with a client library
WebApi.Client that eases you to consume services over HTTP:
1 2 3 4 5 6 7 8 9 10 11