Messin’ with the WCF Web API, part II – Content Negotiation & Formatters

In the last post, I briefly introduced the WCF Web API and walked through the creation of the first service that I constructed as I was experimenting with the framework. WCF Web API has a couple more tricks that it does. In this post I’d like to look at Formatters and their part in Content Negotiation.

Content Negotiation

In section 6.3.2.7 of his dissertation, Architectural Styles and the Design of Network-based Software Architectures, Roy Fielding describes Content Negotiation:

All resources map a request (consisting of method, identifier, request-header fields, and
sometimes a representation) to a response (consisting of a status code, response-header
fields, and sometimes a representation). When an HTTP request maps to multiple
representations on the server, the server may engage in content negotiation with the client in order to determine which one best meets the client’s needs. This is really more of a “content selection” process than negotiation.

So what does this mean? Let’s take a look at this in action. I’ll use the service that I built in the last post.

Using Fiddler I captured the request to retrieve the Xbox game with the ID of 12. That request looks like:

GET http://localhost:1064/MessinWebApi/games/12 HTTP/1.1
Accept: application/xml
Accept-Language: en-US
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Host: localhost:1064

And the response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 405
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcVXNlcnNcTWlrZVxEb2N1bWVudHNcVmlzdWFsIFN0dWRpbyAyMDEwXFByb2plY3RzXE1lc3NpbldlYkFwaVxNZXNzaW5XZWJBcGlPbmVcTWVzc2luV2ViQXBpT25lXGdhbWVzXDEy?=
X-Powered-By: ASP.NET
Date: Mon, 06 Jun 2011 00:51:12 GMT

<?xml version="1.0" encoding="utf-8"?><Game><Id>12</Id><Description>James Cameron's Dark Angel</Description><Developer>Radical Entertainment</Developer><Genre><Id>53</Id><Name>Action</Name></Genre><Name>James Cameron's Dark Angel</Name><Price>49.990000</Price><Publisher>Radical Entertainment</Publisher><Rating><Id>4</Id><Name>T (Teen)</Name></Rating><ReleaseDate>2002-09-01T00:00:00</ReleaseDate></Game>

And again:

GET http://localhost:1064/MessinWebApi/games/12 HTTP/1.1
Accept: application/json
Accept-Language: en-US
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Host: localhost:1064

And the response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 293
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?QzpcVXNlcnNcTWlrZVxEb2N1bWVudHNcVmlzdWFsIFN0dWRpbyAyMDEwXFByb2plY3RzXE1lc3NpbldlYkFwaVxNZXNzaW5XZWJBcGlPbmVcTWVzc2luV2ViQXBpT25lXGdhbWVzXDEy?=
X-Powered-By: ASP.NET
Date: Mon, 06 Jun 2011 00:53:54 GMT

{"Description":"James Cameron's Dark Angel","Developer":"Radical Entertainment","Genre":{"Id":53,"Name":"Action"},"Id":12,"Name":"James Cameron's Dark Angel","Price":49.990000,"Publisher":"Radical Entertainment","Rating":{"Id":4,"Name":"T (Teen)"},"ReleaseDate":"\/Date(1030852800000-0400)\/"}

Now I didn’t make any changes to the service between those two requests. I only changed the Accept header in the request. For the first request I used a value of application/xml and application/json was used in the second. This is Content Negotiation. The client (Fiddler in this case) is using the Accept header to indicate the response formats that it can handle.

Note: To be fair, Content Negotiation can also be used to specify other preferences like encodings and language.

The client is free to indicate more than one format, or Media Type, as the value for the Accept header. The convention is that the values are specified in order of preference. The service is then free to use any of the specified formats that it can reproduce.

The role of rendering a response into the requested media type falls to the Formatters. These are components of the pipeline that I mentioned in the first post. The reason that I’m bringing this up at this point in time, seemingly out of order, is to introduce the base functionality that you get for free: the ability to product XML and JSON straight out of the box.

Custom Formatters

Xml and JSON are covered. You’ll need a custom formatter for anything else and luckily Microsoft has made it super easy to create them. The complexity required is dependent on the representation of the response that you’re trying to create. To demonstrate this, I’m going to create a custom formatter that returns the cover image for each game. When Shawn Wildermuth put together the Xbox games sample database, he included the cover image, as a jpg, in the Games table. My custom formatter is going to take the image and stream it back to the caller.

Note: I wish I could claim this as an original idea but it’s not. The sample application that ships with the WCF Web API has similar functionality. I’m just translating the functionality as appropriate for this data set.

To start I need to have Entity Framework return the Image column when a game is retrieved. To accomplish this I just have to add a property to the Game class with the same name as the field in the table:

    public class Game

    {

        public int Id { get; set; }

        public string Description { get; set; }

        public string Developer { get; set; }

        public Genre Genre { get; set; }

        public string Name { get; set; }

        public decimal? Price { get; set; }

        public string Publisher { get; set; }

        public Rating Rating { get; set; }

        public DateTime? ReleaseDate { get; set; }

        public byte[] Image { get; set; }

    }

Next I create a new folder in the solution called Formatters and add the following new class, ImageFormatter:

    public class ImageFormatter : MediaTypeFormatter

    {

        public ImageFormatter()

        {

            this.SupportedMediaTypes.Add(new MediaTypeHeaderValue("image/jpeg"));

        }

        protected override bool OnCanReadType(Type type)

        {

            return false;

        }

        protected override bool OnCanWriteType(Type type)

        {

            return typeof (Game) == type;

        }

        public override object OnReadFromStream(Type type, Stream stream, HttpContentHeaders contentHeaders)

        {

            throw new NotImplementedException();

        }

        public override void OnWriteToStream(Type type, object value, Stream stream, HttpContentHeaders contentHeaders, TransportContext context)

        {

            var game = value as Game;

            // it would probably be better to write some null image - {shurg}

            if (null == game) return;

            if (null == game.Image) return;

            if (0 == game.Image.Length) return;

            stream.Write(game.Image, 0, game.Image.Length);

            contentHeaders.ContentType = new MediaTypeHeaderValue("image/jpeg");

        }

    }

I believe the code is pretty simple to follow. I just want to point out a couple of things. In the ctor, I’m adding the image/jpeg media type to the collection of media types supported by this formatter. I’ve also provided an override for the OnCanWriteType() method. With those two pieces in place, I’m instructing the WCF Web API pipeline that this formatter can create an image/jpeg representation of instances of Game.

The last piece is to adjust the configuration so that WCF Web API will include the formatter in the pipeline. This is done when the routes are registered in Global.asax:

        public static void RegisterRoutes(RouteCollection routes)

        {

            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

            var config = HttpHostConfiguration.Create()

                .AddFormatters(new ImageFormatter());

            routes.MapServiceRoute<GamesResource>("games", config);

            routes.MapRoute(

                "Default", // Route name

                "{controller}/{action}/{id}", // URL with parameters

                new { controller = "Home", action = "Index", id = UrlParameter.Optional } // Parameter defaults

            );

        }

To retrieve the cover image, I make a request for a specific game, just as in the previous two examples, but use the value "image/jpeg” for the Accept header:

GET http://localhost:1064/MessinWebApi/games/12 HTTP/1.1
Accept: image/jpeg
Accept-Language: en-US
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Host: localhost:1064

Fiddler is kind enough to render the image for me:

Note: the art of the cover image is probably copy written by someone. All rights belong to them.

Formatters are a key component of the pipeline. A formatter will be responsible for creating a representation of a resource and the WCF Web API will handle engaging the correct formatter based on the Accept header in the request.

Messin’ with the WCF Web API

Back in April, Microsoft released the fourth preview of WCF Web API on CodePlex. The intent of the WCF Web API is to make it easier to expose application data and services over HTTP. I’ve seen a lot of people throw in the REST descriptor but I’m not ready to go there yet.

I’ve spent the last couple of weeks playing with the WCF Web API and I’ve decided to put what I’ve learned out there for others. I’m imagining a series of posts but we’ll have to see where my schedule allows me to go.

In this first post, I want to basically put down the steps that I used to get started; consider this a step above the traditional Hello World program.

It’s all about the data

To get started, I first needed something to serve up. There is always the typical Northwind or AdventureWorks database that everyone is probably already familiar with. Instead, I went for something different. Shawn Wildermuth has been kind enough to to make available a database of XBox games. I’m running SQL Server 2008 so I grabbed the appropriate zip file and attached the database that is contained within it.

Next I need a host. A WCF service can be hosted within a number of application. I going to use an ASP.NET MVC 3 Application.

As long as I’m playing with new tech, I’m going to use the Code First features of Entity Framework 4. If you’re following along at home and Entity Framework isn’t already installed, you can get it via NuGet. The package name is EntityFramework.

The next thing is to create some classes that EF will use to expose the data in the Xbox games database. I’ll create three: Game, Genre and Rating and put them in the Models folder. This seemed like a good enough place to store them for now. I can always move them later.

    public class Game

    {

        public int Id { get; set; }

        public string Description { get; set; }

        public string Developer { get; set; }

        public Genre Genre { get; set; }

        public string Name { get; set; }

        public decimal? Price { get; set; }

        public string Publisher { get; set; }

        public Rating Rating { get; set; }

        public DateTime? ReleaseDate { get; set; }

    }

    public class Genre

    {

        public int Id { get; set; }

        public string Name { get; set; }

    }

    public class Rating

    {

        public int Id { get; set; }

        public string Name { get; set; }

    }

The data is accessed through an instance of DbContext. Mine looks like this:

    public class XBoxGames : DbContext

    {

        public DbSet<Game> Games { get; set; }

        public DbSet<Genre> Genres { get; set; }

        public DbSet<Rating> Ratings { get; set; }

        protected override void OnModelCreating(DbModelBuilder modelBuilder)

        {

            base.OnModelCreating(modelBuilder);

            modelBuilder.Entity<Genre>().ToTable("Genres", "SimpleGames");

            modelBuilder.Entity<Genre>().HasKey(g => g.Id);

            modelBuilder.Entity<Genre>().Property(g => g.Id).HasColumnName("GenreID");

            modelBuilder.Entity<Rating>().ToTable("Ratings", "SimpleGames");

            modelBuilder.Entity<Rating>().HasKey(g => g.Id);

            modelBuilder.Entity<Rating>().Property(r => r.Id).HasColumnName("RatingID");

            modelBuilder.Entity<Game>().ToTable("Games", "SimpleGames");

            modelBuilder.Entity<Game>().HasKey(g => g.Id);

            modelBuilder.Entity<Game>().Property(g => g.Id).HasColumnName("GameID");

            modelBuilder.Entity<Game>()

                .HasOptional(g => g.Genre)

                .WithMany()

                .Map(m => m.MapKey("Genre"));

            modelBuilder.Entity<Game>()

                .HasOptional(g => g.Rating)

                .WithMany()

                .Map(m=>m.MapKey("Rating"));

        }

    }

The three properties Games, Genres and Ratings are used to access and manipulate the data using Linq. The OnModelCreating() override is the key to the Code First implementation. This method contains the mapping of the tables to the classes and defines the relationships between the tables, in terms of the classes.

The last item is to tell Entity Framework where to find the database. I’ve added the following connection string to the web.config file:

  <connectionStrings>

    <add name="XBoxGames"

         connectionString="data source=.\SQLEXPRESS; Integrated Security=SSPI; database=XBoxGames"

          providerName="System.Data.SqlClient"/>

  </connectionStrings>

 

Resources

The next step is to expose the game data over HTTP. If you were wondering when I’d get to WCF Web API, well, that’s now.

Like EntityFramework, WCF Web API can be added to the project using NuGet. The package to install is WebApi.All

The nice thing about using NuGet to add libraries to your solution is that it will automatically pickup any dependencies that are required. I needed four.

I’ve decided to create a resource called GamesResource and expose it over HTTP.

    [ServiceContract]

    public class GamesResource

    {

        [WebGet(UriTemplate = "")]

        public List<Game> GetGames()

        {

            using (var gamesRepository = new XBoxGames())

            {

                return gamesRepository

                    .Games

                    .AsNoTracking()

                    .OrderBy(g => g.Id)

                    .Include("Genre")

                    .Include("Rating")

                    .ToList();

            }

        }

    }

Accessing this resource will return a list of all the games, sorted by the game ID.

Note: Returning the entire table via HTTP is probably a very unlikely scenario, if for no other reason than you are stressing your network and server resources. The most common mitigation is to provide either filtering or paging capabilities. I plan to add paging in a future post.

The last thing that I have to do is add some configuration that exposes the new GamesResource. Within Global.asax.cs, I’ve changed the RegisterRoutes() method to:

        public static void RegisterRoutes(RouteCollection routes)

        {

            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

            routes.MapServiceRoute<GamesResource>("games");

            routes.MapRoute(

                "Default", // Route name

                "{controller}/{action}/{id}", // URL with parameters

                new { controller = "Home", action = "Index", id = UrlParameter.Optional } // Parameter defaults

            );

        }

The call to MapServiceRoute() exposes the GamesResource as an Uri whose path starts with “games”. For example, the Uri http://localhost/games would be directed to our GetGames() method within GamesResource.

Starting the site with F5 and navigating to the games resource (for me is: http://localhost:1064/MessinWebApi/games) displays the list of games, encoded using Xml!

Returning a single game

I now want to allow the consumer of my service to fetch a single game using an Uri similar to http://localhost/games/12. This is easy and built into the WCF Web API via the UriTemplate parameter of the WebGet Attribute. This will look familiar if you’ve worked with ASP.Net MVC routing.

I’m going to add a new method to GamesResource called GetSingleGame():

        [WebGet(UriTemplate = "{id}")]

        public Game GetSingleGame(string id)

        {

            using (var gamesRepository = new XBoxGames())

            {

                int idToFind = int.Parse(id);

                return gamesRepository

                    .Games

                    .AsNoTracking()

                    .Include("Genre")

                    .Include("Rating")

                    .Where(g => g.Id == idToFind)

                    .FirstOrDefault();

            }

        }

 

 

GetSingleGame() is very similar to GetGames() with the exception that I have defined a token called {id} within the UriTemplate property of the WebGet attribute and I’ve added a parameter to GetSingleGame() to receive the value. The WCF Web API infrastructure will handle parsing the incoming request to get the ID and making the appropriate call to GetSingleGame().

When put into motion, a request for the game with an ID of 12 (http://localhost:1064/MessinWebApi/games/12) results in the following Xml:

This is just the “tip of the iceberg” for WCF Web Api. There is a very extensible pipeline built into the framework. I plan to explore some of these features in future posts.

One week with the HTC Trophy

On May 26, Verizon made their first phone running the Microsoft Windows 7 OS available, the HTC Trophy. I placed my order before getting ready to go to work and Verizon was nice enough ship it FedEx Next Day (Thanks Verizon!). The phone came on Friday and a spent the entire weekend becoming familiar with it.

I’ve now had the phone for one week and I’ve enjoyed every bit of it. I love the user experience, especially the little jumps and nudges that get your attention and direct you to more features. Previously I had a Blackberry Storm 1 and the Trophy is 10x the phone.

My wife hated the Blackberry Storm. As a test, I gave her the Trophy and asked her to make a phone call. On the Storm, this simple task would frustrate the hell out of her. On the Trophy, she got past the lock screen (I had to give her the code obviously), launched the phone app and made the call. I asked how she knew to get to the keypad on the lock screen, given that she’d never used a WP7 phone before. She didn’t know. “I just did” she replied.

I love the phone but it’s not perfect. I used the Storm for two years and the Blackberry OS is much more mature. It’s only natural that I carried some expectations over to the Trophy. Here are the things that I don’t like or wish that WP7 supported (in no particular order):

- Integrated inbox.
WP7, just like the Storm, is capable of syncing with multiple email accounts. However, the Storm can present a unified inbox. I understand that this might be a feature in the next version of the WP7 OS, Mango.

- You can’t change the base font size
My eyesight isn’t what it used to be. I’ve been told that this is a common complaint from people over the age of 40. It would be nice if you could change the base font size for the device. It is nice that some apps and features support zooming but then you’re stuck panning around the screen.

- Battery life
My sense is that the Storm had a better battery life. I would frequently only recharge the Storm every other day, even though I had enabled Bluetooth and had a number of apps that would download data in the background. On the Trophy, turning off Bluetooth has helped a lot. I rarely enable Wifi. Now, to be fair, multiple people have expressed that “less than optimal” battery life is a common trait for HTC phones.

- Unable to flag an email
I had this on my list since it was something that I could do on the Storm and not WP7. However, I’ve recently discovered that I can flag messages but only for my Exchange and Gmail accounts. I can’t find a way to flag messages coming from my Hotmail account.

- No filters for message syncing
Blackberry supported defining filters as part of the email account subscriptions. I used them to exclude emails coming from discussion lists. I really miss this feature.

That’s it! Just five crummy complaints and none of them serious enough to drive me back to the Storm or another platform.