REST using the WCF Web API – Basics (Part2)

Written on April 16, 2011

Postings published on this series so far:

As written in the first posting, RESTful Services become more and more important nowadays and Microsoft has started to make WCF a first class HTTP citizen by implementing the WCF Web API.

To get started using the Web API, create a new, empty "ASP.NET MVC 3 Web Application" project.

First of all you'll have to get the latest bits which is through the kindness of NuGet almost a no-brainer.

Just add the Package reference to the "WebApi.All" package:

Add Library Package Reference

Install WebApi.All

When finished installing, add a new class to your project called ContactsResource.

First aim of Web API: keep things simple -- that's what we'll start with: a simple Resource returning a list of contacts.

Doing so is a straight forward implementation using Web API:

[ServiceContract]
public class ContactsResource {
    public List<contact> Get() {
        return new List<contact>()
                {
                       new Contact()
                           {
                               Id = 1,
                               Name = "Glenn Block"
                           },
                       new Contact()
                           {
                               Id = 2,
                               Name = "Scott Hanselman"
                           },
                       new Contact()
                           {
                               Id = 3,
                               Name = "Scott Guthrie"
                           }
                };
    }
}

The Contact class itself is also pretty simple -- no magic at all:

public class Contact {
    public int Id { get; set; }
    public string Name { get; set; }
}

To tell Web API which URI to map the contacts resource to, we need to define a URI template. This is done by adding an attribute to the Get()-method.

This attribute also tells Web API which HTTP method to map to the method -- as we want to read the list, according to REST principles the HTTP method of choice is GET.

Thus our attributed method looks like this now:

[WebGet(UriTemplate = "")]
public List<Contact> Get() {

The reason why UriTemplate is an empty string, is that we want to access the list of contacts using the following URI:

http://localhost:3421/contacts

So the next consequential question should be: how does Web API know to call our Get method when the above URI is requested?

Simply put: by it's configuration.

Despite it's WCF background, configuration in Web API is no XML monster but instead a fancy fluent interface.

To get our basic implementation running, just add the following lines to your RegisterRoutes method in Globals.asax.cs:

var configuration =HttpHostConfiguration.Create()
    .SetResourceFactory(new ContactsResourceFactory());
RouteTable.Routes.MapServiceRoute<ContactsResource>("contacts", configuration);

The ContactsResourceFactory implements IResourceFactory having to methods:

public class ContactResourceFactory : IResourceFactory {
    public object GetInstance(Type serviceType, InstanceContext instanceContext, HttpRequestMessage request) {
        return new ContactsResource();
    }

    public void ReleaseInstance(InstanceContext instanceContext, object service) {
        throw new NotImplementedException();
    }
}

Starting up our web application and navigating to

http://localhost:3421/contacts

returns this XML:

Contacts as XML

As REST often is about JSON, Web API covers this also out of the box.

Just start up Fiddler and craft your own HTTP request accepting JSON and hit the Execute button:

handcrafted request accepting JSON

Guess what!

We get some JSON back:

JSON returned

Seeing that we'll finish our first small lap around the Microsoft WCF Web API.

But I'll promise, there's a lot more to come.

In the next postings we'll refactor our example to be more RESTful and we'll test our implementations the BDD way using machine.fakes / machine.specifications.

Furthermore we'll wire things up using the LightCore IoC-Container.

Stay tuned!

Postings published on this series so far:

DotNetKicks-DE Image.aspx&bgcolor=3169AD&fgcolor=FFFFFF&border=000000&cbgcolor=D4E1ED&cfgcolor=000000)