Tell Your Services to Take a REST

Sorry, that’s the best pun I could come up with today. I think all the Guiness and buffet is slowing down my brain. But what better time then now to write a tech post!

REST – REpresentational State Transfer – is a new style of web service that is gaining in popularity, especially with recent support from .NET. The general pricinples of RESTful services include:

  • Application state and functionality is abstracted into resources
  • Every resource has a unique address
  • All resources share a uniform interface for data transfer, including a constrained set of operations and content types
  • Uses a client-server, stateless, cacheable and layered protocol
  • Although you could technically make a RESTful service using any sort of data definition and protocol, the more common ones use HTTP and either XML or JSON to transfer data.

The basic idea behind RESTful services are to present your CRUD operations in the context of resources and make it as available as possible. You, as a consumer of my service, shouldn’t care how I implemented my service or have to code around some sort of messed up data type that might be proprietary to my development platform, and have to worry about what I called my methods. Instead, I tell you what resources I have, what language I use to define them, and how to get to them. For example, getting a list of customers from my service might look like this:

1
GET http://www.rtigger.com/Service/Customers

And I’d return this:

1
{ Customers: [ { ID: 1, First Name: Chad, Last Name: McCallum }, { ID: 2, First Name: Thu, Last Name: Tran } ] }

Or, let’s say I want a specific customer record:

1
GET http://www.rtigger.com/Services/Customers/1

returns:

1
{ ID: 1, First Name: Chad, Last Name: McCallum }

Or, let’s say I want to put a new customer in the database

1
POST http://www.rtigger.com/Service/Customers?FirstName=Willson&LastName=Haw

Which is way more light weight than you average SOAP or .NET remoting call. And as you can see, we cover the 4 points defined above:

Our web service’s actions are defined by resources (making a call to Customers instead of WebService.GetCustomers(); ) – The resource has a unique address (http://www.rtigger.com/Service/Customers) – We’ve effectively constrained the operations by only allowing HTTP verbs (i.e. GET, POST) and the data type (in this case, JavaScript Object Notation) – We use a client-server architecture (web server & client), it’s stateless, entirely cacheable assuming we configure it (that’s next), and I’m not sure what layered means but we’ll say we do it.

Also in comparison to the previous standard SOAP requests, REST over HTTP uses HTTP verbs which alot of web clients automatically support caching of. This means when your client requests a resource it can pass a timestamp and hashcode to the webservice, and the web service can process those arguments and instead of resending the data it can instead simply send “304? – drastically reducing the load on the client, server, and persistance layers (depending on your implementation of cache checking). Other less obvious benefits include:

  • Because the servers aren’t supposed to maintain state anymore, you can have any number of servers answering any and all requests from clients without having to worry about trading session states back and forth
  • There’s less client-side software required because data is transferred in a standard format that’s already present in most programming frameworks (HTTP)
  • No dependencies on vendor-dependent encoding or decoding of information (see: DataSet in SOAP), your RESTful service is publishing information in a open-standard format
  • Fully supports CRUD operations without having to hack anything in
  • No resource mapping, the resource the client is asking for is clearly defined by the URI they’re making the request on
  • With content-type negotiation between the client and the service, can easily add new content types without having to make any drastic changes
  • Because resources have specific URIs, clients could essentially “bookmark” data sources

This type of service definition lends itself more to resources than reporting however. We wouldn’t have something like /Services/Customers/SalesReport, because now we’re changing our resource definition to be specific to an operation, breaking the ‘constrained set of operations’ rule. Technically to do something like that you’d get all the raw sales data to the client and let the client generate the report, which doesn’t work as well in certain environments.

REST is also more of a “guideline” than a formal practice right now, every time a new service pops up that claims to be RESTful there’s usually a huge debate between the diehard REST fans and the more practical “hey, a service, let’s use it” people. In either case, there’s a REST starter kit you can download for visual studio 2008 if you wanted to start playing around with the technology. This lets you prefix your existing web services with a WebGet attribute that defines the URI your web method should be looking for, i.e.

WCF Rest Starter Kit
1
2
3
4
5
6
[WebMethod]
[WebGet(URI="/Customers/{id}")]
public Customer GetCustomerById(int id)
{
    ...
}

Comments