Building Single Page Apps with HTML5, Knockout, jQuery, and Web API - Part 4

It’s about T-4 weeks til my Pluralsight course is available. As I get closer to reaching completion I’ll continue sharing some thoughts on how the SPA is architected.

Web Service Layer and JSON

The X AJAX stands for XML … but most of us use AJAX for requesting/pushing JSON. Most HTML5/JavaScript apps these days deal with JSON which makes having solid and simple server side JSON serving tools (lots of S’s in there) really important. Enter the ASP.NET Web API, which I used an an integral part of the Code Camper SPA for my Pluralsight course, titled “Building Single Page Apps (SPA) with HTML5, ASP.NET Web API, Knockout and jQuery”.

Recently I wrote about how my new end to end course on how to build a SPA is progressing. In this post I share some of my thoughts on how the web service layer is designed in the course. I chose the the ASP.NET Web API because it simplifies web services, is ideal for serving JSON and follows a familiar pattern for me (ASP.NET MVC). I had other options, of course, even in the .NET realm. WCF, ASMX, or even MVC controllers exposing actions. But truth be told, the simplicity of the Web API made it a slam dunk.

More on the Code Camper SPA

Part 1 - The Story Begins (What is the Code Camper SPA?)

Part 2 - Client Technologies

Part 3 - Server Technologies (the Data Layer)

Part 4 - Serving JSON with ASP.NET Web API

Part 5 - HTML 5 and ASP.NET Web Optimization

Part 6 - JavaScript Modules

Part 7 - MVVM and KnockoutJS

Part 8 - Data Services on the Client

Part 9 - Navigation, Transitions, Storage and Messaging

Part 10 - Saving, Change Tracking, and Commanding

Part 11 - Responsive Design and Mobility

Controllers

Controllers are at the heart of the Web API. If you know MVC then this will flow pretty easily for you. Even if you don’t know MVC< the concept is pretty simple. A client makes a HTTP request, it is sent to the server, the Web API routes it to a Controller (a class), and the Controller handles the request. A ASP.NET Web API Controller is simply a class that inherits from ApiController.

The Code Camper SPA has a view which needs a summary list of sessions. So I exposed a method on a Web API Controller to return a list of SessionBrief models. All I have to do from the client was make an ajax request to /api/sessionbriefs

//C# <pre class="csharpcode">public class SessionBriefsController : ApiControllerBase { public SessionBriefsController(ICodeCamperUow uow) { Uow = uow; } public IEnumerable<SessionBrief> Get() { return Uow.Sessions.GetSessionBriefs() .OrderBy(sb => sb.TimeSlotId); } }</pre>

The ApiControllerBase class is a very simple class that defines the Uow property and inherits from the ApiController class. This adds the Unit of Work class instance to all controllers that inherit from it , which in turn allows them to talk to the database (indirectly).

Routes

Web API works off convention over configuration, so ajax calls to /api/sessionbriefs will be routed to it. This route (below) helps route the call to the intended Controller.

routes.MapHttpRoute(
name: ControllerOnly,
routeTemplate: "api/{controller}"
);

Because the ajax request uses an HTTP GET verb, the Get method in the controller is invoked. Then the unit of work (UoW) does its job to get the list of SessionBrief models. Finally, the Web API returns the models as JSON to the client. And when the Code Camper SPA makes PUT, POST, and DELETE requests, they are routed to the Controller’s matching methods for those.

And More

The keys to using the ASP.NET Web API are to set up the routes to the controllers and deciding how to define your controllers and their methods. Once you do that, using the Web API is a breeze. In my course I explain how the different routes in the Code Camper SPA work, how the controllers were designed, and how Ward Bell and I decided to customize them. We ended up using a combination of what I refer to as controller-per-type (a controller services an entity by convention) or custom controllers (mixture of RPC and REST styled calls).

Perhaps my favorite “closet feature” of the Web API is how you can tell it to return models using camelCase. So instead of getting back a SpeakerId property I get speakerId in the JSON. Very simple to implement, but its great and sticks with conventional JavaScript practices.

//C#<pre class="csharpcode">public class SessionBrief { public int Id { get; set; } public string Title { get; set; } public int speakerId { get; set; } }</pre>//JavaScript <pre class="csharpcode">var sessionBrief = { id: 1, title: ‘A Trip to a SPA’, speakerId: 7 };</pre>