Click here to Skip to main content
Click here to Skip to main content
Go to top

Introduction to ASP.NET Web API

, 11 Mar 2013
Rate this:
Please Sign up or sign in to vote.
Introduction to WebAPI. We shall see what it is with two sample real world implementation.

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 
  2. http://www.codeproject.com/Articles/555923/ASP-NET-WebAPI-Hosting-Techniques

  3. Implementing Custom DelegatingHandler in ASP.NET WebAPI
  4. http://www.codeproject.com/Articles/557232/Implementing-Custom-DelegatingHandler-in-ASP-NET-W 

  5. 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 it’s 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 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.

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 it’s 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. Here’s 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. Isn’t 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;
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/self-host-a-web-api

  1. First create a console project
  2. From NuGet manager, search for Microsoft.AspNet.WebApi.SelfHost and install it
  3. Create a controller and make sure it inherits from ApiController.
  4. Implement the required actions based on the HTTP verbs
  5. Now we are ready for hosting.
    1. In program.cs, create an instance of HttpSelfHostConfiguration by specifying the URL to listen, then set the default route map.
    2. 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[]  
    {  
        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()
    {
        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);
        }
        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)
                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.
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.

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();
                },
                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)

Share

About the Author

Ranjan.D
Web Developer
United States United States
Profile
 
Around 9 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, EF
 
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, WCF, WebAPI
 
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 product , link - http://www.codeproject.com/Articles/582535/HealthReunion-A-Windows-Azure-based-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-development-code-signing-to-publishin
 
4. Intel App Innovation Contest 2013 - eHealthCare - http://www.codeproject.com/Articles/635815/eHealthCare
 
5. Grand Prize Winner of CodeProject HTML5 &CSS3 Article Content 2014

Comments and Discussions

 
GeneralMy vote of 5 PinmemberPreben Danielsen29-Jul-13 23:48 
QuestionWhen to use WebAPI PinmemberFabio Franco17-Jul-13 1:17 
AnswerRe: When to use WebAPI PinprofessionalRanjan.D17-Jul-13 4:26 
GeneralRe: When to use WebAPI PinmemberFabio Franco17-Jul-13 6:14 
GeneralMy vote of 5 PinmvpRahul Rajat Singh20-Jun-13 1:29 
GeneralRe: My vote of 5 PinprofessionalRanjan.D20-Jun-13 1:44 
GeneralMy vote of 5 PinmemberMEhran.NET16-May-13 21:34 
GeneralRe: My vote of 5 PinprofessionalRanjan.D17-May-13 1:49 
GeneralMy vote of 5 Pinmembershiva_1923-Apr-13 4:00 
GeneralRe: My vote of 5 PinmemberRanjan.D24-Apr-13 11:25 
GeneralAdd to repository Pinmembersoft stephen28-Mar-13 6:48 
GeneralRe: Add to repository PinmemberRanjan.D28-Mar-13 11:32 
Questionvery nice PinmemberCIDev20-Mar-13 8:30 
AnswerRe: very nice PinmemberRanjan.D20-Mar-13 16:25 
QuestionGood Article Relate to ODATA PinmemberJohn Willson18-Mar-13 6:27 
AnswerRe: Good Article Relate to ODATA PinmemberRanjan.D18-Mar-13 7:11 
GeneralMy vote of 5 PinmemberMihai MOGA11-Mar-13 21:53 
This is a great inspiring article. I am pretty much pleased with your good work. You put really very helpful information. Keep it up once again.
GeneralRe: My vote of 5 PinmemberRanjan.D16-Mar-13 2:33 
GeneralASP.NET Web API PinmemberRekhash11-Mar-13 19:48 
GeneralRe: ASP.NET Web API PinmemberRanjan.D16-Mar-13 2:34 
GeneralMy vote of 5 PinmemberAnurag Gandhi10-Mar-13 21:41 
GeneralRe: My vote of 5 PinmemberRanjan.D11-Mar-13 5:52 
GeneralMy vote of 5 PinmemberRudolf Grauberger6-Mar-13 11:18 
GeneralRe: My vote of 5 PinmemberRanjan.D6-Mar-13 15:42 
Questionexcelent !! PinmemberMember 98893156-Mar-13 9:47 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140926.1 | Last Updated 11 Mar 2013
Article Copyright 2013 by Ranjan.D
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid