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

ASP.NET Web API

, 13 Feb 2014
Rate this:
Please Sign up or sign in to vote.
ASP.NET Web API is a framework for building HTTP services that can be accessed from various clients, such as browsers and mobile devices. ASP.NET Web API was introduced as part of ASP.NET MVC 4; however, it has its origins in WCF as WCF Web API. This new HTTP service model is simple to develop and c
In this article, we will discuss Web API design, concepts, and features, and compare Web API with WCF. 

Implementing a Web API Project

Let’s start our discussion with a sample Web API project. We will be using Visual Studio 2012 as our development environment. Our first step will be to create an ASP.NET MVC 4.0 project based on the Web API template, as shown in Figure 1.

Figure 1: Creating an ASP.NET MVC 4 project based on the Web API template

Next, we’ll create a sample model inside the model folder in the MVC solution. Right click on the Model folder from the solution explorer and select Add -> Class as shown in Figure 2.

Figure 2: Add new Model

For this walk-through, I am using the Product model defined in Listing 1.

public class Product
{
public int Id
{ get; set; }
public string Name
{ get; set; }
public string Category
{ get; set; }
public decimal Price
{ get; set; }}

Listing 1: Defining the Product model

After we create the Product model, we can create a new API controller inside the controllers’ folder to process the Product model. By default, an MVC project based on the Web API template adds two controllers: one inherited from the Controller class and the other from ApiController class. Right-click the controllers folder in Solution Explorer and add a new controller by selecting the Empty API controller option under template as shown in Figure 3.

Figure 3: Add Empty API Controller

The code for the sample controller should look like that shown in Listing 2.

 public class ProductsController : ApiController

    {

        List<Product> products = new List<Product>();
        public IEnumerable<Product> GetAllProducts()
        {
           GetProducts();
           return products;
        }

        private void GetProducts()
        {
           products.Add(new Product {Id = 1, Name = "Television", Category="Electronic", Price=82000});
           products.Add(new Product { Id = 2, Name = "Refrigerator", Category = "Electronic", Price = 23000 });
           products.Add(new Product { Id = 3, Name = "Mobiles", Category = "Electronic", Price = 20000 });
           products.Add(new Product { Id = 4, Name = "Laptops", Category = "Electronic", Price = 45000 });
           products.Add(new Product { Id = 5, Name = "iPads", Category = "Electronic", Price = 67000 });
           products.Add(new Product { Id = 6, Name = "Toys", Category = "Gift Items", Price = 15000 });
        }

        public IEnumerable<Product> GetProducts(int selectedId)
        {
            if (products.Count() > 0)
            {
               return products.Where(p => p.Id == selectedId);
            }
            else
            {
                GetProducts();
                return products.Where(p => p.Id == selectedId);
            }
        }

Listing 2: Adding an ApiController class to the sample project

Run the project and access the API by appending the uniform resource locator (URL) with /api/Products, as in http://localhost:8747/api/Products. You can also access the GetProducts method by passing the SelectedId argument as part of the query string: http://localhost:8747/api/Products?SelectedId=2.

Passing Complex Objects to a Web API Method

Passing a simple value is a straightforward process in Web API, but in most cases you’ll need to pass a complex object as a method parameter. You can pass these objects either by using the [FromUrl] or by using [FromBody] attribute. The [FromBody] attribute reads data from the request body. However, the attribute can be used only once in the method parameter list.

Let us understand the importance of using complex parameters using the code snippet in Listing 3, which expects a complex object, Time, as its input.

public class SampleController : ApiController
    {
        /// <summary>
        /// Get time
        /// </summary>
        /// <param name="t"></param>
        /// <returns></returns>
        public string GetTime(Time t)
        {
            return string.Format("Received Time: {0}:{1}.{2}", t.Hour, t.Minute, t.Second);
        }
    }


    public class Time
    {
        public int Hour { get; set; }
        public int Minute { get; set; }
        public int Second { get; set; }
    }

Listing 3: Passing a complex object as a method parameter

Now, let us try to pass the values to the GetTime method using the Hour, Minute and Second values. As you can see in Figure 4, this will return the null reference exception.

Figure 4: Receiving a null reference exception when calling the GetTime method

Even though we have mentioned the values related to the fields of the Time object, API method is not able to map the values properly to the parameter. Now let’s look at what happens if we modify the code to include the [FromUri] attribute so it can handle the complex object from query string. As you can see in the following snippet, we include the [FromUri] attribute before specifying the Time object:

  public string GetTime([FromUri] Time t)
         { -------------------}

Now if we were to call the method, passing in the same values before, we would observe much different behavior, as shown in Figure 5.

Figure 5: Receiving successful results when calling the GetTime method

Working with the HttpClient API

HttpClient is an extensible API for accessing any services or web sites exposed over HTTP. The HttpClient API was introduced as part of the WCF Web API but is now available as part of ASP.NET Web API in.NET Framework 4.5. You can use HttpClient to access Web API methods from a code-behind file and from services such as WCF.

The code snippet shown in Listing 4 creates an HttpClient object and uses it for asynchronous access to sample API methods. Refer the code comments to understand the code snippet.

   // asynchronous accessing of web api method
        async Task GetData()
        {
            StringBuilder result = new StringBuilder();
            // Define the httpClient object            using (HttpClient client = new HttpClient())
            {
                // Define the base address of the MVC application hosting the web api
                // accessing the web api from the same solution
                client.BaseAddress = new Uri(HttpContext.Current.Request.Url.AbsoluteUri);
                // Define the serialization used json/xml/ etc
                client.DefaultRequestHeaders.Accept.Add(
                    new MediaTypeWithQualityHeaderValue("application/json"));
                // Call the method
                HttpResponseMessage response = client.GetAsync("api/products").Result;
                if (response.IsSuccessStatusCode)
                {
                    // Convert the result into business object
                    var products = response.Content.ReadAsAsync<IEnumerable<Product>>().Result;
                    foreach (var p in products)
                    {
                        result.Append(string.Format("{0} --- [Price: {1} Category: {2}] ", p.Name, p.Price, p.Category));
                    }
                }
                else
                {
                    result.Append(string.Format("Error Code:-{0}  Error Details: {1}", (int)response.StatusCode, response.ReasonPhrase));
                }
            }
            data.Text = result.ToString();
        }

Listing 4: Creating an HttpClient object to access sample API methods

Accessing the Web API from jQuery

From an HTML5 Web application, you can use jQuery to directly access the Web API. You call the API by using the getJSON() method to extract the business object from the result. jQuery can identify internal fields associated with the business object, such as data[i].Price.

The code snippet in Listing 5 retrieves data from our Product API methods and displays the data in a tabular format. Refer the code comments to understand the code snippet.

<head>
    <title></title>
    <script src="Scripts/jquery-1.8.2.js"></script>
     <script type="text/javascript">
         $.getJSON("api/products",
                       function (data) {
                        //Clear the div displaying the result
                           $("#productView").empty();
                          //Create a table and append the table body
                          var $table = $('<table border="2">');
                          var $tbody = $table.append('<tbody />').children('tbody');
                          //data - return value from the Web API method
                           for (var i = 0; i < data.length; i++) {
                                   //add a new row to the table
                               var $trow=$tbody.append('<tr />').children('tr:last');
                                   //add a new column to display Name
                               var $tcol = $trow.append("<td/>").children('td:last')
                                .append(data[i].Name);
                                   //add a new column to display Category
                              var $tcol = $trow.append("<td/>").children('td:last')
                                .append(data[i].Category);
                                 //add a new column to display Price
                               var $tcol = $trow.append("<td/>").children('td:last')
                                .append(data[i].Price);
                           }
                        //display the table in the div
                           $table.appendTo('#productView');
                       });
         </script>
</head>
<body>
    <div id="productView"></div>
</body>
</html>

Listing 5: Using jQuery to retrieve data from the Web API methods

Passing a Parameter from jQuery

In addition to retrieving data from the Web API methods, you can use jQuery to pass parameters back to the Web API. jQuery supports several methods for passing the parameters. The first approach is to use separate parameter set. The following code snippet demonstrates how to pass a single parameter:

  $.getJSON("api/products",
  { selectedId: '4' },
      function (data) {    ….});

You can also pass multiple parameters within a parameter set, as shown in the following snippet:

   $.getJSON("api/products",
           { selectedId: '4', name: 'TV' },
                       function (data) {    ….});

Another approach you can take is to pass a parameter by appending it to the URL query string, as shown in the following snippet:

$.getJSON("api/products?selectedId =4",
                       function (data)  {    ….});

First approach separates the query string or parameter passing from the URL and is appropriate for complex or multiple data passing. Second approach is more suitable for passing one or two parameters.

Scaffolding with Web API

ASP.NET Scaffolding is a code generation framework for ASP.NET Web applications. Visual Studio includes pre-installed code generators for MVC and Web API projects. Visual Studio automatically generates the API code required to perform various operations on the specified model or data source.

Basing Our Scaffold on the Entity Framework

To demonstrate how scaffolding works in a Web API project, we can use the Entity Framework to define our database and generate the Web API methods. First, we need to add an ADO.NET entity data model that defines the data. Our sample data model will be based two tables, Course and Status, as shown in Figure 6.

Figure 6: Adding an entity data model based on the Course and Status tables

After we define the data model, we can generate the Web API controller that corresponds to the model. Right-click Controller and then click Add Controller, which lunches the Add Controller dialog box. In the Controller name text box, type the controller name. Then, from the Template drop-down list, select the API controller with read/write actions, using Entity Framework template, as shown in Figure 7.

Figure 7: Adding a controller based on the data model

Next, select one of the tables from the Model class drop-down list and, in the Data context class drop-down list, specify the data context created as part of the ADO.NET entity data model. Listing 6 shows the automatic code generated for the CourseController API controller. Notice that it contains methods for to support get, put, post, and delete operations that correspond to the selected model.

public class CourseController : ApiController
{
   private SampleDBEntities db = new SampleDBEntities();
   // GET api/Course
   public IEnumerable<Course> GetCourses()
   {
     return db.Courses.AsEnumerable();
   }
// GET api/Course/5
     public Course GetCourse(int id)
    {
       Course course = db.Courses.Single(c => c.CourseId == id);
       if (course == null)
        {
      throw new HttpResponseException(Request.CreateResponse(HttpStatusCode.NotFound));
        }
    return course;
}
// PUT api/Course/5
 public HttpResponseMessage PutCourse(int id, Course course)
 {
    if (!ModelState.IsValid)
   {
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
}
if (id != course.CourseId)
{
return Request.CreateResponse(HttpStatusCode.BadRequest);
}
db.Courses.Attach(course);
db.ObjectStateManager.ChangeObjectState(course, EntityState.Modified);
try
{
db.SaveChanges();
}
catch (DbUpdateConcurrencyException ex)
{
return Request.CreateErrorResponse(HttpStatusCode.NotFound, ex);
}
return Request.CreateResponse(HttpStatusCode.OK);
}
// POST api/Course
public HttpResponseMessage PostCourse(Course course)
{
if (ModelState.IsValid)
{
db.Courses.AddObject(course);
db.SaveChanges();
HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.Created, course); 
response.Headers.Location = new Uri(Url.Link("DefaultApi", new { id = course.CourseId }));
return response;
}
else
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
}
}
// DELETE api/Course/5
public HttpResponseMessage DeleteCourse(int id)
{
Course course = db.Courses.Single(c => c.CourseId == id);
if (course == null) {
return Request.CreateResponse(HttpStatusCode.NotFound);
}
db.Courses.DeleteObject(course);
try
{
db.SaveChanges();
}
catch (DbUpdateConcurrencyException ex)
{
return Request.CreateErrorResponse(HttpStatusCode.NotFound, ex);
}
return Request.CreateResponse(HttpStatusCode.OK, course);
}
protected override void Dispose(bool disposing)
{
db.Dispose();
base.Dispose(disposing);
}
}

Listing 6: Code generated for the CourseController API controller

The Web API scaffolding feature reduces the development effort required to generate the API methods necessary to perform CRUD (create, read, update, delete) operations in different models.

Routing in ASP.NET Web API

Web API uses routing to match uniform resource identifiers (URIs) to various actions. The WebApiConfig file, located inside the App_Start node in Solution Explorer, defines the default routing mechanism used by Web API. The mechanism is based on a combination of HTTP method, action, and attribute. However, we can define our own routing mechanism to support meaningful URIs.

For example, in our sample Web API project, we use /api/Products to retrieve product details. However, we can instead use api/Products/GetAllProducts by modifying the default routing logic to include {action} as part of the URI, as shown in the following code snippet:

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

After we update the route, we can use the ActionName attribute in our Web API method to specify the action name, as the follow snippet shows:

[ActionName("GetAllProducts")]
public IEnumerable<Product> GetAllProducts()
{……………………………..} 

NOTE: Use the [NonAction] attribute to indicate that the Web API method is not an API action method.

We can also use an HTTP method or Acceptverbs attribute to specify the HTTP action required to access the Web API method. For example, the following snippet uses the HttpGet and HttpPost methods:

[HttpGet]
public IEnumerable<Product> GetProducts(int selectedId)
{………….. }
[HttpPost]
public void AddProduct(Product p)
{………….. }  

For multiple methods, use the Acceptsverbs attribute, as shown in the following snippet:

[AcceptVerbs("GET","PUT")]
public IEnumerable<Product> GetProducts(int selectedId)
{………….. } 

Web API 2 also makes it possible to use attributes in our routing. Refer to the article "Attribute Routing in Web API v2" by Dino Esposito for more details.

Implementing Multiple Serialization Methods

Web API supports numerous serialization methods, including XML, JSON, and MessagePack. In the sections to follow, we’ll take a closer look at how to implement these three methods and then compare their behavior. Before doing that, however, let’s modify the sample Web API project to return bulk data so we can better understand and compare the performance of the serialization methods. Listing 7 shows how the GetProducts() method updated to return bulk data.

        private void GetProducts()
        {
            for (int i = 0; i < 5000; i++)
            {
                products.Add(new Product { Id = i, Name = "Product -  "+i,
                    Category = "The ASP.NET and Visual Web Developer teams have released the ASP.NET and Web Tools 2012.2 update, which extends the existing ASP.NET runtime and adds new web tooling to Visual Studio 2012. Whether you use Web Forms, MVC, Web API, or any other ASP.NET technology, there is something cool in this update for you.",
                    Price = 1 });
            }
        }

Listing 7: Updating the GetProducts() method

Using JSON Serialization

Web API uses JSON as its default serialization method. As a result, when you run the Web API project, the results are automatically returned in the JSON format. For example, to retrieve details from Products, you need only use the syntax http://<<server>>:<<port>>/api/Products to return the results in the JSON format.

Using XML Serialization

To use the XML serialization method in a Web API project, you must modify the Global.asax file by inserting the following two lines of code at the end of Application_Start() method:

GlobalConfiguration.Configuration.Formatters.RemoveAt(0);
GlobalConfiguration.Configuration.Formatters.XmlFormatter.UseXmlSerializer = true;

After implementing the XML serialization method, you can retrieve details from Products by using the syntax http://<<server>>:<<port>>/api/Products, the same syntax used for JSON.

Using MessagePack Serialization

To use the MessagePack serialization method, you must first install MessagePack (http://msgpack.org/). MessagePack is available as NuGet package. You can also download the source code from GitHub and build the application in Visual Studio.

Once you’ve installed MessagePack, use the MsgPack.dll file to add a reference to the MessagePack library. Next, create a custom media type formatter that uses MessagePack to serialize the Web API data. Listing 8 shows the code for a media type formatter based on a GitHub sample (https://gist.github.com/filipw/3693339).

public class MediaTypeFormatterCompatibleMessagePack : MediaTypeFormatter
    {
        private readonly string _mime = "application/x-msgpack";
        Func<Type, bool> IsAllowedType = (t) =>
            {
                if (!t.IsAbstract && !t.IsInterface && t != null && !t.IsNotPublic)
                    return true;
                if (typeof(IEnumerable).IsAssignableFrom(t))
                    return true;
                return false;
            };
        public MediaTypeFormatterCompatibleMessagePack()
        {
            SupportedMediaTypes.Add(new MediaTypeHeaderValue(_mime));
        }
        public override bool CanWriteType(Type type)
        {
            if (type == null)
                throw new ArgumentNullException("Type is null");
            return IsAllowedType(type);
        }
        public override Task WriteToStreamAsync(Type type, object value, System.IO.Stream stream, HttpContent content, TransportContext transportContext)
        {
            if (type == null)
                throw new ArgumentNullException("type is null");
            if (stream == null)
                throw new ArgumentNullException("Write stream is null");
            var tcs = new TaskCompletionSource<object>();
            if (type != typeof(string) && typeof(IEnumerable).IsAssignableFrom(type))
            {
                value = (value as IEnumerable<object>).ToList();
            }
            var serializer = MessagePackSerializer.Create<dynamic>();
            serializer.Pack(stream, value);
            tcs.SetResult(null);
            return tcs.Task;
        }
        public override Task<object> ReadFromStreamAsync(Type type,Stream stream, HttpContent content, IFormatterLogger formatterLogger)
        {
            var tcs = new TaskCompletionSource<object>();
            if (content.Headers != null && content.Headers.ContentLength == 0)
                    return null;
            try
            {
                var serializer = MessagePackSerializer.Create(type);
                object result;
                using (var mpUnpacker = Unpacker.Create(stream))
                {
                    mpUnpacker.Read();
                    result = serializer.UnpackFrom(mpUnpacker);
                }
                tcs.SetResult(result);
            }
            catch (Exception e)
            {
                if (formatterLogger == null) throw;
                formatterLogger.LogError(String.Empty, e.Message);
                tcs.SetResult(GetDefaultValueForType(type));
            }
            return tcs.Task;
        }
        public override bool CanReadType(Type type)
        {
            if (type == null)
                throw new ArgumentNullException("type is null");
            return IsAllowedType(type);
        }
    }

Listing 8: Building a MessagePack media type formatter

After you create your media type formatter, you must update the Global.asax file to use the formatter. Insert the following code at the end of Application_Start() method to use MessagePack serialization:

 GlobalConfiguration.Configuration.Formatters.Clear();
 GlobalConfiguration.Configuration.Formatters.Add(new MediaTypeFormatterCompatibleMessagePack());

Comparing Serialization Methods

You can test JSON, XML, and MessagePack serialization in Web API by using Fiddler tool. Open Fiddler and navigate to the Request Builder tab. Enter the MessagePack Web API URL in Request Builder and add application/x-msgpack as Content-Type under the Request Headers section, as shown in Figure 8.

Figure 8: Request Builder in Fiddler

Now, click the Execute button to invoke the Web API method. Repeat the process for JSON and XML based Web API methods, without specifying the Content-Type request header. Compare the results in terms of body size, bytes received, and elapsed Time as shown in Figure 9.

Figure 9: Comparing serialization methods in Fiddler

As shown in above figure, result from message pack based serialization will be compressed compared to other serializations. Size of the JSON result will be less compared to that of XML based serialization.

Help Page Generation from XML Documentation

By default, Web API provides help pages related to the API methods defined in the project. We can generate the help pages from the XML documentations provided as part of the method definition.

To create the help pages, expand the Areas node in Solution Explorer (shown in Figure 10) and then open the HelpPageConfig.cs file

Figure 10: Accessing the HelpPageConfig.cs file in the sample Web API project

In the HelpPageConfig.cs file, un-comment the following statement:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"))); 

Next, enable XML documentation by selecting the XML documentation file option in the Build section of the project’s properties, as shown in Figure 11. Copy the filename specified in the config file to the XML documentation file option.

Figure 11: Enabling the XML documentation file in the Web API project

Now, let’s add the XML documentation to our sample API controller, as shown in Listing 9. Just before each method definition, specify "///" to get the default XML documentation for the method. Modify further with more specific comments.

         /// <summary>
        /// Get All products for our Sample
        /// </summary>
        /// <returns></returns>
        public IEnumerable<Product> GetAllProducts()
        {
                 ---------------
        }
 
        /// <summary>
        /// Return the details of selected product depends on the product id passed.
        /// </summary>
        /// <param name="selectedId"></param>
        /// <param name="name"></param>
        /// <returns></returns>
        public IEnumerable<Product> GetProducts(int selectedId)
        {
      
                 ------------------
        }

Listing 9: Adding XML documentation to the sample API controller

Once you’ve updated the controller, run the application and navigate to API link at the top-right corner of the browser screen, as shown in Figure 12.

Figure 12: Viewing the API link in the application window

Click the API link to open the help page. Notice the XML documentation comments that had been added to the controller, as shown in Figure 13.

Figure 13: Viewing the comments in the Web API help file

WCF via Web API

WCF supports numerous protocols and messaging formats. With Web API, we can create only HTTP-based services. Obviously, we can create HTTP services with WCF, but they’re hidden inside different abstraction layers. In addition, implementation is more complex with WCF than with Web API. HTTP implemented on WCF uses the HTTP post model, and we may not be able to use the main features associated with HTTP protocols such as Caching and Status Code. By using Web API, we can perform all activities like get, post, and put, and we can use different HTTP protocol features.

WCF requires complex binding and address manipulation and configurations, but Web API is straightforward and simple to use. Web API is also a better choice for RESTfull service creation. You can find a detailed comparison between WCF and Web API in the MSDN article "WCF and ASP.NET Web API."  

 Update 1: 

For passing complex data type to a Web API method using jQuery, use the JSON.Stringify to properly pass the JSON data to the method.

For example, following code snippet shows, how you can pass the custom data "user" to a Web API method 

   var user = {};
    user.name = 'Mathew';
    user.job = 'ITA';
    user.rating = 'Good';
 $.getJSON("api/getEmployeeDetail",
      {JSON.stringify(user)},
                       function (data) { ......}
 ); 

 

License

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

Share

About the Author

ambilykk
Architect TCS
India India
I have over 10 years of experience working on Microsoft Technologies. I am carrying the passion on Microsoft technologies specifically on web technologies such as ASP.Net, HTML5, jQuery and Ajax. My interests also include TFS, Azure, Windows 8, Visual Studio 2010. Technology adoption and learning is my key strength and technology sharing is my passion.
 
Microsoft MVP: Connected Service Developer
Follow on   Twitter   LinkedIn

Comments and Discussions

 
QuestionNice and Detailed Article. PinmemberImran Abdul Ghani2-Sep-14 2:00 
GeneralExcellent! PinmemberShanaya Singh6-Aug-14 5:41 
GeneralMy vote of 5 PinmemberHumayun Kabir Mamun24-Jul-14 19:47 
QuestionGood article Pinmembersenthilmonster23-Jul-14 20:14 
GeneralThanks Pinmemberpareshpbhayani3-Jul-14 18:13 
QuestionGood Explanation !! PinmemberShalini Anita Chellaraj20-Jun-14 13:12 
QuestionGood article PinmemberHvishal8828-May-14 0:59 
Generalwell explained , five to you Pinmemberrodri_ogri18-Apr-14 4:56 
GeneralMy vote of 5 PinprofessionalRenju Vinod19-Mar-14 20:14 
GeneralNice... PinmemberNitij Kumar14-Feb-14 6:03 
GeneralRe: Nice... Pinmemberambilykk18-Feb-14 17:55 

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 13 Feb 2014
Article Copyright 2014 by ambilykk
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid