Lewis Benge

When .NET 3 launched, Microsoft developers where introduced to a drastically new way of dealing with application communication. Windows Communication Foundation (WCF) had taken the web service concept we knew from ASP.NET and radicalised it drastically to cater for the most common networking stacks and communication protocols. We where no longer dealing with simply SOAP/XML services, our world was now opened up to TCP Steams, bi-directional networking traffic, and integration into existing networking components such as MSMQ. Yet the revolution that was .NET and its evolution in .NET 3.5 never supported the API concepts we gradually saw materialising within the Web 2.0 applications that where making their presence in not only our lives, our phones, but even our Hello World demos we would soon see in tutorials and presentations around the world.

RESTful Services

Made infamous by applications such as Twitter, the concept of Representational State Transfer (REST) is not necessarily new. First introduced in 2000 by Roy Fielding, one of the original authors of the HTTP specification, REST is an architecture based on client-server communication whereby clients initiate a request to a server, with the server processing requests and returning appropriate resource. Usually associated with HTTP, it is not necessary limited to the protocol however many of the RESTful API’s we see today do base themselves natively on the HTTP architecture. The primary reason for this is the HTTP protocol has a rich vocabulary of verbs used to define resources and associated service methods thus helping to confirm to one of the architectures core principals of Uniform Interfaces. The remaining RESTful principals of client – server , stateless, cacheable, and layered systems (see table 1 for definitions) are also tightly coupled to HTTP but can easily be adopted in other protocols such as  Remote Procedure Call (RPC).

Table 1 – RESTful Architecture Principals

Client – Server-Clients should be separated from a server by a uniformed interface. This separation of concerns means that clients are not concerned with data storage, which remains internal to each server so that the portability of each client code is improved. Server are not concerned with the user interface or user state, so that servers can be simpler and more scalable.

Stateless – The client-server communication is further constrained by no client context being stored on the server between requests. Each request from any client contains all of the information necessary to service the request, and any session state is held on the client. The server can be stateful; however this is constraint requires that server-side state by addressable by a URI.

Cacheable – Responses must implicitly or explicitly define themselves as cacheable or not prevent clients reusing stale or inappropriate data in response to further requests.

Layered system – A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve systems scalability by enabling load balancing and by providing shared caches. They may also enforce security policies.

Uniformed interface – The uniform interface between client and server simplifies and decouples the architecture which enables each part to evolve independently.

When the popularity of RESTful services become apparent within the industry, it was unfortunate that .NET developers struggled somewhat with the architecture. WCF was never originally designed around with REST support in mind, and at the time the alternative of ASP.NET was not necessarily the best framework either, although the introduction of ASP.NET MVC did provide a stop-gap solution for many people. In late 2008 the WCF team released the WCF REST toolkit which extended the System.ServiceModel assembly that provided the underlying WCF engine and allowed service endpoints to become REST enabled. The solution was adequate for people familiar with the WCF architecture, but at the same time was complicated to get up and running and difficult to extend. It was for this, and other reasons that it was not widely adopted.

With the introduction of .NET 4 the latest version of the WCF framework for the first time natively supported REST services.  WCF 4.0 simplified the deployment of REST services using the .NET framework, removing the new from .SVC files, service contract interfaces, and all of the configuration required within the web.config creating services now followed similar structure to that found in ASP.NET MVC routes,easily done with apply attribute to a class, and its methods and registering routes in the Global.asax. Simplicity was good, but unfortunately it also brought with it restrictions with extensibility and flexibility.

WCF Web API

In late October 2010, Glenn Block and the WCF Team provided us with the first insight in to the future of REST services within WCF through a CodePlex project currently known as WCF Web API. With the last version released within the past month at MIX 11 the new framework builds upon the simplicity of REST support within .NET 4 but provides us the the advanced support for customisation and personalisation of our REST APIs.  The primary difference between WCF WEB API and the REST Support is within its layered architecture (fig 1), (which in itself is a natural progression of the REST principals). Unlike the native support within .NET 4, the Web API channels all incoming request from its HTTP endpoint (or listener as it is called within this implementation) via a HTTP Channel Stack. At this low level within the service, extensions  to the framework can be injected (via configuration) to handle transport-level concerns such as security, logging or error handling. The HTTP Channel Stack is also responsible for the serialisation/deserialization of the incoming raw messages into the frameworks proprietary objects HttpRequestMessage. 

Once the object is successfully passed through the channel stack it is then the responsibility of the dispatcher to ensure that the message is routed to the correct method on the service implemented by the developer. Within Web API the server interface can be defined by more than just the URI. The dispatcher natively supports all of the HTTP Verbs, it also has an extensibility point at this level for defining custom media types, called a HTTP Processor. The dispatcher is also responsible for de-serialising the body of the request message into .NET types.  With the combination of the URI, Verb, and Content Type the dispatcher will then pass the HttpRequestMessage  to the HTTP Service.

The Http Service is the where the developer actually builds out the logic of the service. This resource is similar to a service contract in terms of traditional WCF, and even carry the same class attributes. As with WCF 4 native REST support, and other WCF implementations to expose methods to the service you decorate them with attributes.

Figure 1 – Web API Architecture (source CodePlex) 

The final part of the Web API architecture is a client library for .NET closely tied to the HttpRequestMessage and HttpResponseMessage objects found within the Web API framework. Although traditional HTTP libraries such as WebRequest will work the WCF team have built this client to conform to a tighter representation of the HTTP specification to ensure it works with all HTTP REST calls, as well as provide a set of extension methods that handles the deserialisation of the HTTP Body to .NET types and classes.

The extensible architecture are not the only bonuses provided by the Web API framework, as of the latest release their is now container support for IOC libraries which in turn provides better support for separation of concerns and testability. The configuration model now also uses a fluent API, which provides a cleaner, easier method of handling extensibility. Web API also supports IQueryable services in a similar fashion to WCF Data Services thus allowing data queries to be passed into the service using the OData URI protocol.

Getting Started with Web API

So I’ve talked a lot about simplicity, so how easy is it to get a REST service up and running? Well lets give it a go. First up Visual Studio, and open up a new Empty Web Application project. From there I am going to use Nuget (package name WebApi.All) to add the assemblies in to my project, but if you prefer just download the latest from the CodePlex site. 

Once you’ve added the assemblies the first thing we want to do is create some data classes so we have something for our service to return. So lets start by creating some domain objects around a store catalog:

public class Category {     public string Description { get; set; }

     public string Name { get; set; }

     public List<Product> Products { get; set; }

 }

public class Product   {       public int Id { get; set; }

       public string Name { get; set; }

       public string Description { get; set; }

       public double Price { get; set; }

   }

Once we’ve done that we want to create a stub data context, and basic repository to allow us to have some data access flowing:

public class CatalogContext   {       public IEnumerable<Category> GetData()       {           return new[]                      {                          new Category                              {                                  Description = "A selection of technology titles",                                  Name = "Technology",                                  Products = new List<Product>()                                                 {                                                     new Product {Id = 1, Description = @"Mixing provocative insights and cliched criticisms, Postman defines the U.S. as a society in which technology is deified to a near-totalitarian degree.", Name = " Technopoly: The Surrender of Culture to Technology", Price = 12.99},                                                     new Product {Id = 2 ,Description = @"Applying the lessons of history to modern-day dilemmas, Nye defies much common wisdom about the power of technology in society. With irony and wit, he exhorts us not to succumb to defeatist notions of technological determinism but to take charge of our own human destinies", Name = "Technology Matters: Questions to Live With ", Price = 10.76},                                                     new Product {Id = 3, Description = @"This historical account achieves its basic aim of demonstrating that, with the exception of quite recent history, technology has always influenced science, not the other way round.", Name = "Science and Technology in World History: An Introduction", Price = 17.82}                                                 }                              },                              new Category                              {                                  Description = "A selection of titles to read with the light on",                                  Name = "Horror",                                  Products = new List<Product>()                                                 {                                                     new Product {Id = 4, Description = @"Dracula begins with the journal of Jonathan Harker, a young solicitor on the way to Transylvania to give information to the mysterious Count Dracula about his new estate in London. Dracula takes the young man prisoner, and Jonathan sees many strange and evil things in the castle before escaping and fleeing into the night. He later decides that he must have been mad.", Name = "Dracula", Price = 15.95},                                                     new Product {Id = 5, Description = @"The story of Victor Frankenstein's monstrous creation and the havoc it caused has enthralled generations of readers and inspired countless writers of horror and suspense. Includes the author's own 1831 introduction.", Name = "Frankenstein", Price = 2.99},                                                     new Product {Id = 6,Description = @"This University of Nebraska Press edition is a small, exquisitely produced paperback. The book design, based on the original first edition of 1886, includes wide margins, decorative capitals on the title page and first page of each chapter, and a clean, readable font that is 19th-century in style. Joyce Carol Oates contributes a foreword in which she calls Dr. Jekyll and Mr. Hyde a mythopoetic figure like Frankenstein, Dracula, and Alice in Wonderland, and compares Stevenson's creation to doubled selves in the works of Plato, Poe, Wilde, and Dickens.", Name = "The Strange Case of Dr. Jekyll and Mr. Hyde ", Price = 1.59}                                                 }                              }                      };       }   }

public class CatalogRespository    {        private readonly CatalogContext _context;

        public CatalogRespository()        {            _context = new CatalogContext();        }

        public IEnumerable<Category> GetCategories()        {            return _context.GetData();        }

        public Category GetCategoriesByName(string name)        {            return _context.GetData().First(x => x.Name == name);        }

        public IEnumerable<Product> GetProductsByCategory(string category)        {            return GetCategoriesByName(category).Products;        }

        public Product GetProductById(int id, string category)        {            return GetProductsByCategory(category).First(x => x.Id == id);        }    }

[ServiceContract]public class CatalogService{     ...}

This is what you would see in a standard WCF service. The next thing we want to do is add some methods. For each method we want exposed to the REST service we also need to apply an attribute. For Web API this attribute is [WebInvoke()], and it accepts a few different properties. In the interests of simplicity the only two properties we are interested in is UriTemplate and Method.  Starting with the first, UriTemplate is a familiar property seen with ASP.NET MVC and is used for defining a URI to that particular resource. The URI template is a string that can consist of a route, and parameters, an example of this is “/Product/{id}” where Product is the route which is used to seperate resources, and {id} is mapped to the parameter the method accepts. You can also nest multiple parameters for a method in a UriTemplate too such as “{Category}/{ProductId}”. The next property we are going to use is Method, this is simply the HTTP Verb we want associated with our resource, and in this example we simply want to use “GET”.

So inside our Service Contract lets construct some methods, and add the necessary attributes (you’ll also notice in my hold I am retrieving the data using the repository we created earlier):

[ServiceContract]   public class CatalogService   {       private readonly CatalogRespository _repository; 

       public CatalogService()       {           _repository = new CatalogRespository();       }

       [WebInvoke(UriTemplate = "", Method = "GET")]       public IQueryable<Category> GetCategories()       {           return _repository.GetCategories().AsQueryable();       }

       [WebInvoke(UriTemplate = "{category}", Method = "GET")]       public Category GetCategoryByName(string category)       {           return _repository.GetCategoriesByName(category);       }

       [WebInvoke(UriTemplate = "/{category}/{id}", Method = "GET")]       public Product GetProductByCategoryAndId(string category, int id)       {           return _repository.GetProductById(id,category);       }   }

So that is our service now finished. The last thing to do is to wire-up our routes. To do this add a new Global Application file (Global.asax) to the project. Once added we want to edit the Application_Start event and add in a Route Table object. This is exactly the same class as used by ASP.NET MVC (System.Web.Routing) , but Web API provides some extensions with the Microsoft.ApplicationServer.Http.Activation assembly. What this class essentially is going to do is intercept requests to the URI and instead of passing them to ASP.NET resources it is going to hand off to the HTTP Channel Stack as discussed earlier. This is done via the MapServiceRoute<T>() method,  so lets add this in to our file:

public class Global : System.Web.HttpApplication   {       protected void Application_Start(object sender, EventArgs e)       {           RouteTable.Routes.MapServiceRoute<CatalogService>("catalog");       }

   }

The MapRoute<T>() method accepts a type which should relate to our HTTP Service which we have defined by our service contract. The constructor parameter it accepts is the base resource URI which in our instance is “catalog”. With that we are done, so if you now fire up the application and open up the URI in the browser you should see the following:

http://{yourURL}/catalog

 http://{yourURL}/catalog/Technology

http://{yourURL}/catalog/Technology/1

As you may have noticed on our base resource (/catalog) our method implemented the IQueryable interface, so this means we can actually implement the OData URI protocols to also sort out catalog, so try loading this URI in the browser to see the impact:

http://{yourURL}Catalog?$top=1&$orderby=Name

If you want to create a full CRUD solution, simply swap our the verbs you declared on the METHOD property of the WebInvoke attribute, and have you method accept your domain objects, or HttpRequest<T> where T is your domain object (depending on whether you need full access to the incoming request) Web API will handle the serialisation for you.

So that’s all it takes to now get up and running with WCF and REST. It’s along way from where we’ve come from; it’s simple, it extensible, and you can be up and running in minutes. So I urge you now to go forth and experiment with the API and provide your feedback to the WCF team, so they can improve the process along the way – and hopefully make WCF 5 the frame work we want it to be.

I’ll be posting a few more advanced posts on Web API in the coming weeks, so please stay tuned to my blog for more details. If you would like the source code for this sample project you can find it here.