Easy REST

In designing software there is a fundamental trade-off between simplicity and power.  Great products have just the right mix of the two.  When it comes to REST the team has been grappling with this balance.  If you have seen the WCF REST Starter Kit then you have seen a feature packed solution for building RESTful services.  However, some people say they want more simplicity.  Today I’m going to show you the easiest way to build a RESTful service.  For the scenario let’s imagine I’m building a website for a conference.  I want the website to provide a REST service that returns one or all conference sessions.

Step 1 – Describe your resource

The resource is just a class that will be serialized to return the data to your callers.  It is typically a very simple class with public properties.

     public class ConferenceSession
    {
        public string ID {get;set;}
        public string Title { get; set; }
    }

Notice this is a very simple class with no attributes, interfaces or base class required.

Step 2 - Create the Information Model

It makes sense to keep this simple. We are going to provide a service that returns one or all conference sessions

URI Method Description
Conference.svc/ GET Returns all sessions
Conference.svc/{id} GET Returns session {id}

Step 3 – Describe the contract

Since this model is so common, I created a generic contract that you can use over and over again if you use this information model.

 using System.ServiceModel;
using System.ServiceModel.Web;
namespace EasyREST
{
    [ServiceContract]
    public interface IEasyREST<T> where T:class
    {
        [OperationContract]
        [WebGet(UriTemplate="/{id}")]
        T GetItem(string id);
        [OperationContract]
        [WebGet(UriTemplate = "/")]
        T[] GetItems();
    }
}

 

Step 4 – Create your service

Now I can create a service for my website.  These are the manual steps, you can create a template that already has most of this done if you want.

  1. Add a reference to System.ServiceModel.Web and System.ServiceModel
  2. Right click and select Add New Item… then choose WCF Service from the list.  Name the service Conference
  3. Visual Studio created an interface for your service called IConference – you won’t need this so delete it
  4. Delete the entire <System.ServiceModel> section from web.config – you won’t need this either
  5. Edit the markup for Conference.svc to add the WebServiceHostFactory.  Right click on Conference.svc and select View Markup and add the highlighted line
 <%@ ServiceHost 
Language="C#" 

Debug="true" 

Service="EasyREST.Conference" 

CodeBehind="Conference.svc.cs"

Factory="System.ServiceModel.Activation.WebServiceHostFactory" %>
  1. Edit the service implementation to use the IEasyREST<T>
     public class Conference : IEasyREST<ConferenceSession>
    {
        public ConferenceSession GetItem(string id)
        {
            ConferenceSession session =  ConferenceGateway.GetSession(id);
            if (session == null)
                WebOperationContext.Current.OutgoingResponse.SetStatusAsNotFound();
            return session;
        }
        public ConferenceSession[] GetItems()
        {
            return ConferenceGateway.GetSessions();
        }
    }

Bottom Line

This is a very simple reusable REST solution.  The question is… is this enough?  I suspect for a large number of RESTful services this will provide just what you are looking for.  It’s easy to grasp and easy to use is it not?

I’d be interested in hearing what you think about it.  I’ve added this project to the MSDN Code Gallery at http://code.msdn.microsoft.com/easyrest.