In-Depth

Implementing Binary JSON in ASP.NET Web API 2.1

Visual Studio 2013 came with a new version of Web API. The Web API 2.1 update includes a host of new features, including support for Binary JSON. Learn how to leverage BSON by building a Web API 2.1 service.

• By Sam Nasr
• 05/19/2014

The Web API framework allows developers to quickly create services using MVC-like conventions. It offers the flexibility of creating REST style services, and serving up data in a variety of formats, including the newly supported Binary JSON (BSON) format. This article will focus on building a Web API 2.1 service utilizing the new BSON Media-Type Formatter.

ASP.Net Web API is a relatively new technology from Microsoft, released initially with the Microsoft .NET Framework 4.5. It allows a single Web service to communicate with various clients in various formats such as XML, JSON and OData. (I discussed the introduction of ASP.NET Web API is in a previous article). With Visual Studio 2013, Microsoft released ASP.NET Web API 2 in October 2013, followed by an update to Web API 2.1 in January 2014. Some of the new features in 2.1 include:

• Global Error Handling
• Attribute Routing Improvements
• Help Page Improvements
• IgnoreRoute Support
• BSON Media-Type Formatter
• Support for Async Filters
• Query Parsing for the Client Formatting Library

BSON is a binary-encoded serialization of JSON-like objects (also known as documents) representing data structures and arrays. BSON objects consist of an ordered list of elements. Each element contains Field Name, Type and Value.

Field names are strings. Types can be any of the following:

• string
• integer (32-bit)
• integer (64-bit)
• double (64-bit)
• date (integer number of milliseconds)
• byte array
• boolean
• null
• BSON object
• BSON array
• Regular expression
• JavaScript code

The primary advantages of BSON are that it's lightweight with minimal spatial overhead, easy to parse, and efficient for encoding and decoding.

To demonstrate, I'll create a sample ASP.NET Web API 2.1 application in ASP.NET MVC 5, using Visual Studio 2013. This solution will be very similar to the one I discussed in my previous article (following the premise of building an inventory app for a used car lot), which will allow for comparison and contrast of old features to new features. I'll call it CarInventory21, to reflect version 2.1 of the ASP.NET Web API.

First, I create an ASP.NET Web Application, choosing an Empty template with MVC folders and core references, as seen in Figure 1 and Figure 2.

Next, I add a class to the Model folder, calling it Car.cs, shown in Figure 3 and Figure 4.

This class contains the following structure, representing each car in inventory (it's been slightly modified from its counterpart in the previous article):

public class Car
{
  public Int32 Id { get; set; }
  public Int32 Year { get; set; }
  public string Make { get; set; }
  public string Model { get; set; }
  public string Color { get; set; }       
}

Next, I add an Empty Web controller by right-clicking the Controllers folder | Add | Controller, as shown in Figure 5.

Afterward, when prompted for the type of controller to scaffold, I chose an Empty controller (see Figures 6-8) for the sake of keeping the sample project thin and clutter-free.

Like other ASP.NET MVC projects, the controller isn't required to be in the Controllers folder, but it's a good practice and is highly recommended. Unlike typical ASP.NET MVC projects that inherit from the Controller class, the ASP.NET Web API controller inherits the ApiController class.

Following the implementation from the previous article, I won't use a database but instead instantiate the records in code. I will also create two action methods within the controller: one to retrieve all car records, and the other to retrieve only a specific record using the ID field. The complete listing of Controllers\CarController.cs is shown in Listing 1.

using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
using CarInventory21.Models;  //Added manually


namespace CarInventory21.Controllers
{
  public class CarController : ApiController
  {
     
    Car[] cars = new Car[] 
    { 
      new Car { Id = 1, Year = 2012, Make = "Cheverolet", Model = "Corvette", Color = "Red" }, 
      new Car { Id = 2, Year = 2011, Make = "Ford", Model = "Mustang GT", Color = "Silver" }, 
      new Car { Id = 3, Year = 2008, Make = "Mercedes-Benz", Model = "C300", Color = "Black" } 
    };

    public IEnumerable<Car> GetAllCars()
    {
      return cars;
    }

    public IHttpActionResult GetCar(int id)
    {
      var car = cars.FirstOrDefault((c) => c.Id == id);
      if (car == null)
      {
        return NotFound();
      }
      return Ok(car);
    }
  }
    
}

Looking at other portions of the project, a WebApiConfig.cs is created in the App_Start folder of the solution by default. As the name suggests, this file is for globally configuring the ASP.NET Web API. Before configuring the solution for BSON, I first need the references for the BSON library. This is done automatically by installing the NuGet package Microsoft ASP.NET Web API 2.1 Client Library, as seen in Figure 8.

Installing the NuGet package will also require accepting the license agreement (see Figure 9).

Because I want to display only BSON, I will add the following lines at the bottom of the Register method in the App_Start\WebApiConfig.cs file:

config.Formatters.Clear();                             // Remove all other formatters
config.Formatters.Add(new BsonMediaTypeFormatter());   // Enable BSON in the Web service

These calls will first clear and remove all other formatters the ASP.NET Web API will use for responding to requests. Then it will add a new instance of the BSON formatter to the empty list, effectively making BSON the only response type available. The complete listing can be seen in Listing 2.

using System.Net.Http.Formatting;
using System.Web.Http;

namespace CarInventory21
{
  public static class WebApiConfig
  {
    public static void Register(HttpConfiguration config)
    {
      // Web API configuration and services

      // Web API routes
      config.MapHttpAttributeRoutes();

      config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
      );
            
      config.Formatters.Clear();                             
      // Remove all other formatters
      config.Formatters.Add(new BsonMediaTypeFormatter());   
      // Enable BSON in the web service
    }
  }
}

So far I've built the model and the controller. The only remaining item is a view. For a view, I'll create a simple HTML page. This will serve as a test page and also allow IIS Express to host the ASP.NET Web API. To add a Web page, I right-click on the project and select Add | HTML Page, calling it Index.html.

By default, the links to access this new ASP.NET Web API are:

• http://localhost:15324/api/car -- to retrieve all car records
• http://localhost:15324/api/car/car_id -- to retrieve a specific car by ID

Routing is a detailed topic not addressed in this article. However, you can learn more about it here.

To help facilitate testing, I modify the newly-created page to include all links. The full listing can be found in Listing 3.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Test Page</title>
</head>
<body>
    <br />    
    To retrieve all car: <a href="/api/car"> /api/car </a> <br />
    <br />
    To retrieve car #1: <a href="/api/car/1"> /api/car/1 </a> <br />
    To retrieve car #2: <a href="/api/car/2"> /api/car/2 </a> <br />
    To retrieve car #3: <a href="/api/car/3"> /api/car/3 </a> <br />
    <br />
</body>
</html>

At this point, the project is ready to run, resulting in the output seen in Figure 11.

Clicking on the first link to retrieve all cars will download all cars to the browser in BSON format. Currently there's no code to display the retrieved records, so the browser will simply prompt to save the records to a file. Opening the file in Visual Studio will yield the records in Binary format, as seen in Figure 12.

Reading through the file, you'll see the various hex characters decorating the ASCII characters. These are characteristics of the BSON format. At this stage the ASP.NET Web API is ready to be consumed by clients.

(I'll discuss the various ways an ASP.NET Web API can be consumed by a client process in upcoming articles.)

Lightweight, Flexible Data
ASP.NET Web API 2.1 is currently the latest release from Microsoft. It offers a variety of new features, including the new BSON format. It can be utilized like other formats, but offers a lightweight representation of binary data in a format similar to JSON, which gives Web API 2.1 more flexibility while still remaining simple and easy to configure.

• Get Code Download