Lost In Tangent

When WCF was first released we all wallowed in its magnificent glory. It was so chocked full of features it would make any modest girl blush (including yours truly). But despite its voluminous power, some couldn’t help but feel like it was missing something. Something simple but extremely powerful. WCF thought these naysayers were crazy and insisted that not only was he all that, but that he also had a bag of chips.

One evening WCF was lounging at the bar, as he did most nights, and a beautiful little something in the corner caught his eye. She was clean and pretty, and appeared to be very successful and likable. In fact she was surrounded by an entourage of dread lock toting individuals who appeared to worship her like it was some kind of religion. WCF was besides himself in jealously and decided he needed to be a part of this circle of friends. So he walked up to the lady and asked for her name. “I’m REST” she said, “and these are the RESTafarians“. One thing led to another, and long story short, WCF and REST ended up hooking up. Who’s the winner of this match made in heaven? We all are

So the question is, how exactly can a developer begin to create RESTful services, or even append this new found functionality to existing ones? Thankfully enough its ridiculously easy (even I can understand it). What I’m going to develop is a service that will report what the currently playing song is in iTunes, which other people could call (for whatever reason). Making it RESTful adds volumes to the ease of use, and leaves the windows of possibilities wide open.

First I’m going to make a simple service contract:

Obviously nothing special is going on here. So how do we make this thing work in a RESTful fashion?

Notice the difference? All we did was salt the GetCurrentTrack method with a new attribute called WebGet. This attribute simply marks a method as being callable via an HTTP GET operation, namely a REST call. There are more properties for the WebGet attribute, which we’ll examine later, but for now suffice it to say that our service contract is now configured for accepting REST requests.

Now let’s create our service implementation:

Once again, nothing special is going on here. The service simply calls a class to retrieve the current iTunes track. I’m not going to go into how I actually determine the playing track in this article, but if you’re curious you can examine the source code.

So now that we’ve got our service completed all we need now is to create our host, which we’ll implement as a console application for this demonstration:

Notice that I’m not creating a ServiceHost but rather a WebServiceHost. This is a new class added in .NET 3.5 that serves the purpose of hosting WCF services that make use of the new HTTP GET/REST functionality. It is basically a wrapper of the ServiceHost that sets some property values so that we don’t have to.

The last peice of this equation is the configuration file:

The only point of interest here is the binding being used. WebHttpBinding is a new binding added in .NET 3.5 specifically for HTTP GET/REST services.

And that’s it. Pretty simple huh? Surprisingly, we’ve only introduced 3 new classes: WebGetAttribute, WebServiceHost, and WebHttpBinding. Everything else is just plain old WCF. So let’s see this thing work. I start up the host and then navigate to “http://localhost:8731/GetCurrentTrack” in my browser:

As you can see I’m currently getting my chill on to some wonderful Joy Wants Eternity. I change tracks and refresh:

So you can see the service works beautifully. A client could easily subscribe to this and parse the XML at will.

Now what if we wanted this service to be exposeable to our fellow JavaScript enthusiasts out there? All we have to do is tweak the service contract:

All we’ve had to introduce is a single enumeration to our arsenal, but the power of this service just went up ten fold. Let’s run the host and hit the service:

With one ridiculously trivial change to our contract we just got JSON serialization absolutely free. Now anyone could easily use their favorite JavaScript library, make a RESTful call to our service, and use the returned object.

The last thing I’ll show in this article is the ability to add a URI template to your RESTful service contract. If you wanted to modify the URL of the service method (to make it prettier for instance) you can easily achieve this using the UriTemplate property of the WebGet attribute:

By doing this, instead of navigating to “http://localhost:8731/GetCurrentTrack”, we can now navigate to “http://localhost:8731/ThisIsSoCool/IKnowRight/GetTrack”. Being able to build flexible, clean URLs for your method can add a lot to your service when needed.

What if we wanted to pass parameters to our RESTful service?

The UriTemplate let’s us easily map method parameters to values from the incoming URL, so I could now call the service at “http://localhost:8731/ThisIsSoCool/IKnowRight/GetTrack/Jonathan” and it would fire the GetCurrentTrack method passing it “Jonathan”. Could it get any sweeter than that? I think not!

So WCF and REST went on to live a life of prosperity and joy, infecting .NET developers around the world with their intuitive coding model and flexible interface. People couldn’t be happier, and it would seem that their union couldn’t have been more timely. Was it your everyday love story? Not quite. What is better than Moonstruck? I’d sure like to think so…

Download the source code for this sample here.