asp.net-web-api2 Getting started with asp.net-web-api2 What and why Asp.Net Web API2?

Example

What and Why ?

Asp.Net’s Web API2 is the latest version of Web API. It is an easy way to implement a RESTful web service using all of the goodness that the Asp.Net framework provides. Once you understand the basic principles of REST, then a Asp.net Web API2 will be very easy to implement. Web API2 is built on Asp.Net’s modular, pluggable pipeline model. This means that when a server hosting a web API2 receives a request, it passes through Asp.Nets request pipeline first. This enables you to easily add your own modules if you find that the default capabilities are not enough for your needs. With the recent announcements on ASP.net vNext this also means you can potentially host your Web API2 outside of Windows Server which opens up a whole range of usage cases. See here for detail.

How works ?

Web API2 uses the Controller and Action concepts from MVC. Resources are mapped directly to controllers; you would typically have a different controller for each of your main data entities (Product, Person, Order etc). Web API2 uses the Asp.Net routing engine to map URLs to controllers. Typically, APIs are held within a /api/ route which helps to distinguish API controllers from other non-API in the same website.

Actions are used to map to specific HTTP verbs, for example you would typically have a GET action which returns all of the entities. This action would respond to /api/Products (where ‘products’ is your controller) and would look something like this:

 public IEnumerable<string> Get()
 {
     return new string[] { "value1", "value2" };
 }

You may also have a GET action which accepts a specific ID and returns a specific entity. It would respond to /api/Products/81 and would look something like this:

public string Get(int id)
 {
    return "value";
 }

There are many great hidden benefits to using Web API which you may not realise but actually save you a lot of work.

Web API2 is part of the ‘One Asp.Net’

Web API2 is part of the ‘One Asp.Net’ family which means that it natively supports all of the great shared features you may currently use with MVC or web forms, this includes (these are just a few examples):

• Entity Framework
• Authorisation and identity
• Scaffolding
• Routing

Serialization and Model Binding

Web API2 is setup by default to provide responses in either XML or JSON (JSON is default). However, as a developer you do not need to do any conversion or parsing – you simply return a strongly typed object and Web API2 will convert it to XML or JSON and return it to the calling client, this is a process called Content Negotiation. This is an example of a GET action which returns a strongly typed Product object.

 public Product GetProduct(int id)
 {
    var product = _products.FirstOrDefault(p => p.ID == id);
    if (product == null)
    {
       throw new HttpResponseException(HttpStatusCode.NotFound);
    }
    return Request.CreateResponse(HttpStatusCode.OK, product);
 }

This also works for incoming requests using a feature called Model Validation. With Model Validation, Web API2 is able to validate and parse incoming response body data to a strongly typed object for you to work with in your code. This is an example of model binding:

 public HttpResponseMessage Post(Product product)
 {
     if (ModelState.IsValid)
     {
         // Do something with the product (not shown).
 
         return new HttpResponseMessage(HttpStatusCode.OK);
     }
     else
     {
         return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
     }
 }