Introduction to ASP.

NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

Articles Web Development ASP.NET Howto

Introduction to ASP.NET Web API

By Ranjan.D, 11 Mar 2013
4.89 (66 votes)

Download Manage Contacts Web API Download Web API Basic Sample Download WinPhone Contacts Manager

Introduction
ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. With WebAPI content negotiation, we can return data based on the client requests. What I mean is, if the client is requesting the data to be returned as JSON or XML, the WebAPI framework deals with the request type and returns the data appropriately based on the media type. By default WebAPI provides JSON and XML based responses. WebAPI is an ideal platform for building pure HTTP based services where the request and response happens with HTTP protocol. The client can make a GET, PUT, POST, and DELETE request and get the WebAPI response appropriately. In summary, the WebAPI is An HTTP Service Designed for broad reach Uses HTTP as an Application protocol, not a transport protocol Some more interesting articles on WebAPI 1. ASP.NET WebAPI Hosting Techniques http://www.codeproject.com/Articles/555923/ASP-NET-WebAPI-Hosting-Techniques 2. Implementing Custom DelegatingHandler in ASP.NET WebAPI http://www.codeproject.com/Articles/557232/Implementing-Custom-DelegatingHandler-in-ASP-NET-W

1 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

3. Implementing Custom Media Formatters in ASP.NET WebAPI http://www.codeproject.com/Articles/559378/Implementing-Custom-Media-Formatters-in-ASP-NET-We

Web API Architecture

We shall see below the Web API architecture when you are hosting WebAPI in ASP.NET and self-hosting through console or Windows service.

Routing configuration in WebAPI is slightly different from ASP.NET MVC Routing. The WebAPI uses HttpRouteCollection and Route. The WebAPI team has reused the routing logic of MVC in WebAPI. The only reason why its a different routing is in order to keep the WebAPI from having its dependency on ASP.NET Routing. The team decided to make it independent so that WebAPI will not have ASP.NET class dependencies and it can be hosted in console or a Windows service as self-hosting. While in ASP.NET WebAPI routing, the system will not only register the HttpRoute object but also it will create a wrapper Route object and in the ASP.NET routing engine. The significant difference that you can see here is you will not have access to Routing data in message handlers when you are trying to access the same in self-hosting, the reason is the route configuration is set and it will run at a later point in the life cycle. The other significant difference between the ApiController and the normal MVC controller is with WebAPI ApiController, the actions are dispatched by default based on the HTTP request. However there is a flexibility to override it so that the WebAPI will use the action name to select the action method within the ApiController. What is Content Negotiation in Web API This is something which you will here frequently in WebAPI. Content negotiation is the process of selecting the best representation for a given response when there are multiple representations available. The underling Web

2 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

API framework implements the content negotiation and that is the reason why and how the client can request data with a specific media type. By default the Web API returns data in JSON format, however while requesting for a resource we can specify the media type to return so that the WebAPI knows what you are requesting for and select the proper formatter to output the data.

How to Implement Web API? We shall see a generic implementation of Web API. We have to create a class which derives from ApiController. The methods defined in the WebAPI controller map to the HTTP methods. If you have a method name prefixed with GET, it means you are trying to return some data based upon the GET request. You just have to make sure that whatever actions you are implementing must be prefixed with the right request type (GET, POST, PUT, and DELETE). Note: The method name need not be Get () or Post () etc. However it does not limit to prefixing the request types. You can still implement the actions with different naming but you have to make sure to use the suitable action filters [HttpGet] , [Post] , [Put], [Delete]. Routing in ASP.NET Web API? To determine which action to invoke, the framework uses a routing table. Below is the default route which is configured as a part of Global.asax. The routing is quite similar to what we define for MVC controllers:
routes.MapHttpRoute( name: "Default", routeTemplate: "api/{controller}/{id}", defaults: new { id = RouteParameter.Optional } );

The Web API framework receives an HTTP request, it tries to match the URI against one of the route templates in the routing table. If no route matches, the client receives a 404 error.

3 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

Action Parameters in WebAPI simple types are taken from URI - Route data, query parameters. Complex types come from the body - Configured MediaTypeFormatters are used to desterilize the request body based on the content type - JSON, XML and form-URL-encoded are supported out of the box, also we can override using [FormUrl], [FormBody], [ModelBinder], custom parameter binding. How to host a Web API ? You can go with self or web hosting. Self-hosting in any Windows process (e.g., console application or Windows service) Web hosting - using the ASP.NET pipeline on top of Internet Information Services (IIS). You have to make a reference and use the below ones if you are going with self-hosting. Here is the code snippet for self-hosting Web API.
using System.Web.Http; using System.Web.Http.SelfHost; var config = new HttpSelfHostConfiguration("http://localhost:8080"); config.Routes.MapHttpRoute( "API Default", "api/{controller}/{id}", new { id = RouteParameter.Optional }); using (HttpSelfHostServer server = new HttpSelfHostServer(config)) { server.OpenAsync().Wait(); Console.WriteLine("Press Enter to quit."); Console.ReadLine(); }

In the above hosting, the application listens to the specified URL localhost 8080. You need administrator privileges for that. If you are facing any issues like HTTP could not register URL then you will have to run the below statement in the command prompt as Administrator:
netsh http add urlacl url=http://+:8080/ user=machine\username

How to manually run the content negotiation and why its required? We have seen above the content negotiation is something which is built inside the WebAPI which will make use of formatters to decode and encode the HttpRequest and HttpResponses. So the question comes, when exactly we need to manually run the content negotiation logic. Heres one that we can think of, say you are consuming a third party service which always returns data in JSON format. Your client is accepting or willing to process XML based responses or maybe you have other clients consuming data in different formats like JSON or XML. In such scenarios you can think of building a WebAPI as a wrapper around the services that you are consuming. Isnt it meaningful to build something and return data based on the media type? Below is the generic code which runs the content negotiation
// Get the IContentNegotiator IContentNegotiator negotiator = Configuration.Services.GetContentNegotiator(); // Run content negotiation to select a formatter MediaTypeHeaderValue mediaType;

4 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

MediaTypeFormatter formatter = negotiator.Negotiate( typeof(Contact), Request, Configuration.Formatters, out mediaType); // Create a response message with an object content using the selected formatter HttpResponseMessage response = new HttpResponseMessage() { Content = new ObjectContent<contact>(contact, formatter), RequestMessage = Request };

Get the content negotiator instance and run the Negotiate method with the following parameters, the type of object you want to return, request object, the default formatters, and out param for the media type. At last create a HttpResponseMessage and format the content as per the media formatter which is obtained while doing content negotiation.

Background
This article is just a start off, a beginner article for WebAPI. A basic understanding of MVC is sufficient to understand and implement ASP.NET WebAPI.

Using the code

We shall create a very basic sample WebAPI project and host it in console and make a request from browser. I am referring to the example mentioned in http://www.asp.net/web-api/overview/hosting-aspnet-web-api/selfhost-a-web-api 1. 2. 3. 4. 5. First create a console project From NuGet manager, search for Microsoft.AspNet.WebApi.SelfHost and install it Create a controller and make sure it inherits from ApiController. Implement the required actions based on the HTTP verbs Now we are ready for hosting. a. In program.cs, create an instance of HttpSelfHostConfiguration by specifying the URL to listen, then set the default route map. b. Create an instance of HttpSelfHostServer with the above configuration and open the connection and wait for the client requests. 6. Requesting for Products:, just copy paste or type in the URL http://localhost:8080/Products in the browser and hit Enter. That's all you should do to be able to see the response. When you are requesting for Products with the URL http://localhost:8080/Products, the GetAllProducts method of ApiController will serve the request. Similarly if you wish to get product by ID, you will have to pass the ID while making a request to the WebAPI controller. Here is an example http://localhost:8080/Products/1, upon requesting, the GetProductsById method will be invoked and it will return a single product based on the product ID.
public class ProductsController : ApiController { Product[] products = new Product[] {

5 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } }; public IEnumerable<product> GetAllProducts() { return products; } public Product GetProductById(int id) { var product = products.FirstOrDefault((p) => p.Id == id); if (product == null) { throw new HttpResponseException(HttpStatusCode.NotFound); } return product; } public IEnumerable<product> GetProductsByCategory(string category) { return products.Where(p => string.Equals(p.Category, category, StringComparison.OrdinalIgnoreCase)); } } static void Main(string[] args) { var config = new HttpSelfHostConfiguration("http://localhost:8080"); config.Routes.MapHttpRoute( "API Default", "api/{controller}/{id}", new { id = RouteParameter.Optional }); using (HttpSelfHostServer server = new HttpSelfHostServer(config)) { server.OpenAsync().Wait(); Console.WriteLine("Press Enter to quit."); Console.ReadLine(); } }

Now we will see another sample implementation of WebAPI handling GET, PUT, POST, DELETE requests. For demonstration purpose, I have created a WebAPI based Contact Manager application. Use case: 1. Ability to manage contacts. The user should be able to add/update/delete contacts. 2. Display all contacts in the Home page. Below is the Contacts Controller implementation. We are encapsulating all the CRUD operations in a repository named ContactRepository.
public class ContactsController : ApiController { private static readonly IContactRepository _contacts = new ContactRepository(); // Get All Contacts public IEnumerable<contact> Get() {

6 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

return _contacts.GetAllContacts(); } // Get Contact by Id public Contact Get(int id) { try { Contact contact = _contacts.GetContact(id); return contact; } catch (Exception ex) { throw new HttpResponseException(Request.CreateResponse(HttpStatusCode.NotFound, ex.Message)); } } // Insert Contact public HttpResponseMessage Post(Contact value) { try { if (ModelState.IsValid) { Contact contact = _contacts.AddContact(value); var response = Request.CreateResponse<contact>(HttpStatusCode.Created, contact); return response; } else { return Request.CreateResponse(HttpStatusCode.InternalServerError, "Model state is invalid"); } } catch (Exception ex) { return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message); } } // Update Contact by Id public HttpResponseMessage Put(int id, Contact value) { try { _contacts.UpdateContact(id, value); } catch (Exception ex) { return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message); } return Request.CreateResponse(HttpStatusCode.OK); } // Delete Contact by Id public HttpResponseMessage Delete(int id) { try { _contacts.RemoveContact(id); } catch (Exception ex) { return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message);

7 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

} return Request.CreateResponse(HttpStatusCode.OK); } }

Below is the code for the Contact Repository. It is built on Entity Framework Code First Approch. The Repository is composed of ContactsDbContext, with its help we are performing CRUD operations.
public class ContactRepository : IContactRepository { private ContactsDbContext context; public ContactRepository() { context = new ContactsDbContext(); } public IEnumerable<contact> GetAllContacts() { try { return context.Contacts.ToList(); } catch { throw; } } public Contact GetContact(int id) { try { return context.Contacts.SingleOrDefault(c => c.Id == id); } catch { throw; } } public Contact AddContact(Contact item) { try { context.Contacts.Add(item); context.SaveChanges(); return item; } catch { throw; } } public bool RemoveContact(int id) { try { var contact = context.Contacts.SingleOrDefault(c => c.Id == id); if (contact == null)

8 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

throw new Exception(string.Format("Contact with id: '{0}' not found", id.ToString())); context.Contacts.Remove(contact); context.SaveChanges(); return true; } catch { throw; } } public bool UpdateContact(int id, Contact item) { try { var contact = context.Contacts.SingleOrDefault(c => c.Id == id); if( contact == null) throw new Exception(string.Format("Contact with id: '{0}' not found", id.ToString())); contact.Name = item.Name; contact.Email = item.Email; contact.Phone = item.Phone; context.Entry(contact).State = EntityState.Modified; context.SaveChanges(); return true; } catch { throw; } } } public class ContactsDbContext : DbContext { public ContactsDbContext() : base("name=ContactsDbContext") { } public DbSet<contact> Contacts { get; set; } }

Setting Up the Database for Managing Contacts Open solution - WebAPI - ManageContacts in Visual Studio and follow the below steps: 1. (Optional step) Open web.config and make changes to the connection string "ContactsDbContext" if required. 2. Go to Tools -> Library Package Manager -> Package Manager Console Run Update-Database command as shown below. You should be able to see the command run successfully without throwing any errors.
PM> Update-Database Specify the '-Verbose' flag to view the SQL statements being applied to the target database. No pending code-based migrations. Applying automatic migration: 201302171855006_AutomaticMigration.

9 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

Running Seed method.

Rendering contacts (MVC + Web Api Controller) Here is a code snippet for HTTP GET verb. We are making an AJAX request to get all the contacts. The request will hit the Home controller and it will execute the "ContactsGrid" action. Within the action, we are creating an instance of the WebAPI controller, get all the contacts, and then return a partial view - ContactsGrid.
function GetContacts() { $.ajax({ url: '/Home/ContactsGrid', type: "GET", success: function (response) { $("#contactsGrid").html(response); }, error: function (data) { $("#contactsGrid").html(data.responseText); } }); }

Add contacts with WebAPI Below is the code snippet for adding a new contact. Here we are making a jQuery request with the URL to the WebAPI controller, passing the contact information by serializing the data as a JSON object in the HTTP Request body. The content negotiation within the WebAPI will understand and decode the contact information. Note - Set the proper content type while making a request. Below you can see the content type set to 'application/json'.
function AddContact() { var contact = { Name: $('#Name').val(), Email: $('#Email').val(), Phone: $('#Phone').val() }; $.ajax({ url: '/Api/Contacts', type: 'POST', data: JSON.stringify(contact), contentType: "application/json;charset=utf-8", success: function (data) { alert('Contacts added successfully'); GetContacts(); }, error: function (data) { alert('Problem in adding contacts:' + data.responseText); } }); }

Deleting contacts with WebAPI Below is the code snippet for deleting contacts. We make a jQuery request with the URL to the WebAPI controller. You will also notice that by setting the request type to 'DELETE', it helps to execute the Delete method in the Contacts WebAPI Controller.

10 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

function DeleteContact(id) { $.ajax({ url: '/Api/Contacts/'+ id, type: 'DELETE', success: function (data) { GetContacts(); }, error: function (data) { alert('Problem in deleting contacts:' + data.responseText); } }); }

Update contacts with Web API Below is the code snippet for updating the contacts. We are using the jQuery model dialog. We will get the contact to update and then show up a dialog so that we can edit the contact. When we click on the Update button, we will make an AJAX request with the URL to the WebAPI controller. You can also notice the request type is 'PUT' and we are also serializing the contacts before making the request. If the update operation succeeds, we will call the GetContacts() method so that it will update the contacts grid.
function EditContact(id) { $.ajax({ url: '/Home/GetContactsById/' + id, type: "GET", success: function (response) { $("#editContact").html(response); }, error: function (data) { $("#editContact").html(data.responseText); } }); $(dialog).dialog('open') } dialog = $("#editContact").dialog({ autoOpen: false, resizable: false, closeOnEscape: true, show: "explode", hide: "explode", width: 300, title: "Edit Contact", buttons: { Update: function () { var contact = { Name: $('#Name').val(), Email: $('#Email').val(), Phone: $('#Phone').val() }; $.ajax({ url: '/Api/Contacts/' + $('#Id').val(), type: 'PUT', data: JSON.stringify(contact), contentType: "application/json;charset=utf-8", success: function (data) { GetContacts();

11 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

}, error: function (data) { alert('Problem in updating contacts:' + data.responseText); } }); $(dialog).dialog("close"); }, Cancel: function () { $(dialog).dialog("close"); } } });

Web.config changes In order to execute HTTP requests for DELETE, PUT, etc., we need to add the below mentioned line under <system.webserver> so that the application handles all types of requests.
<modules runallmanagedmodulesforallrequests="true">

Points of Interest
It was fun in learning and writing an article on WebAPI. I hope this article will be helpful for enthusiastic peoples who are eager to learn and implement some interesting stuffs in new technology. This article won't be completed if I don't thank all peoples who helped me in understanding WebAPI (to some extent). Please feel free to comment your opinion about this article, code, or whatever you feel like telling me. Also if you like this article, don't forget to vote me.

History
Version 1.0 - 2/18/2013 - Initial version with two sample applications.

License
This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

12 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

Ranjan.D
Web Developer United States

Profile Around 8 years of professional software development experience in analysis, design, development, testing and implementation of enterprise web applications for healthcare domain with good exposure to object-oriented design, software architectures, design patterns, test-driven development and agile practices. In Brief Analyse and create High Level , Detailed Design documents. Use UML Modelling and create Use Cases , Class Diagram , Component Model , Deployment Diagram, Sequence Diagram in HLD. Area of Working : Dedicated to Microsoft .NET Technologies Experience with : C# , J2EE , J2ME, Windows Phone 8, Windows Store App Proficient in: C# , XML , XHTML, XML, HTML5, Javascript, Jquery, CSS, SQL, LINQ Software Development Database: Microsoft SQL Server, FoxPro Development Frameworks: Microsoft .NET 1.1, 2.0, 3.5, 4.5 UI: Windows Forms, Windows Presentation Foundation, ASP.NET Web Forms and ASP.NET MVC3, MVC4 Coding: WinForm , Web Development, Windows Phone, WinRT Programming Healthcare Domain Experience CCD, CCR, QRDA, HIE, HL7 V3, Healthcare Interoperability Others: TTD, BDD Education B.E (Computer Science) CodeProject Contest So Far: 1. Windows Azure Developer Contest - HealthReunion - A Windows Azure based healthcare

13 of 14

1/24/2014 12:09 PM

Introduction to ASP.NET Web API - CodeProject

http://www.codeproject.com/Articles/549152/Introduction-to-ASP-NET...

product , link - http://www.codeproject.com/Articles/582535/HealthReunion-A-Windows-Azurebased-healthcare-pro 2. DnB Developer Contest - DNB Business Lookup and Analytics , link http://www.codeproject.com/Articles/618344/DNB-Business-Lookup-and-Analytics 3. Intel Ultrabook Contest - Journey from development, code signing to publishing my App to Intel AppUp , link - http://www.codeproject.com/Articles/517482/Journey-from-developmentcode-signing-to-publishin 4. Intel App Innovation Contest 2013 - eHealthCare - http://www.codeproject.com/Articles /635815/eHealthCare

Comments and Discussions

68 messages have been posted for this article Visit http://www.codeproject.com/Articles/549152 /Introduction-to-ASP-NET-Web-API to post and view comments on this article, or click here to get a print view with messages.

Permalink | Advertise | Privacy | Mobile Web02 | 2.8.140120.2 | Last Updated 11 Mar 2013

Article Copyright 2013 by Ranjan.D Everything else Copyright CodeProject, 1999-2014 Terms of Use

14 of 14

1/24/2014 12:09 PM