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 https://code.msdn.microsoft.com/easyrest.

Comments

• Anonymous
  February 25, 2009
  PingBack from http://www.clickandsolve.com/?p=14367

• Anonymous
  February 25, 2009
  Thank you for submitting this cool story - Trackback from DotNetShoutout

• Anonymous
  February 25, 2009
  But what's about UpdateItem(id, title)?

• Anonymous
  February 26, 2009
  Most RESTful services are read only so this service does not include Add/Update/Delete methods although it would be trivial to do so.

• Anonymous
  March 01, 2009
  #.think.in infoDose #19 (23rd Feb - 27th Feb)

• Anonymous
  March 02, 2009
  Pick of the week: Paying Down Your Technical Debt General Leveraging ILMerge to Simplify Deployment and Your Users’ Experience : Daniel Cazzulino demonstrates how you can easily combine multiple assemblies into a single assembly. DDD Step By Step : Casey

• Anonymous
  March 04, 2009
  Well, I tried something similar with normal SOAP services, I had a big problem: what does it happen when you want to expose two entities? It would be fantastic if I could mix various servicecontracts in the same WSDL.

• Anonymous
  March 04, 2009
  You can surface only 1 resource per .SVC file.  So for a conference website I might have a Sessions.svc file that exposes the session resource and a Speakers.svc file that exposes the speaker resource.