The easiest way to explain the issues we encountered when implementing REST is to work through the design principles we followed. I think much of our trouble came from the fact that we come from a web applications background, not a SOAP services background. I’m hoping that by laying out our REST design, some of the Microsoft gurus can help us do things “the WCF way.” And perhaps we can help the WCF team out by highlighting a handful of places where we found WCF unintuitive.
Fundamentally, the REST pattern is about making resources available. This means that each item stored within your system can be accessed by someone with the correct permissions. Every one of these items has its own unique address, and its address should not change. This consistency is important, because it allows both people and computer programs to remember and reference items in your system.
Note that we’re talking about resources or items. In contrast with the SOAP model of web services, which allows programmers to invoke procedures on remote computers, REST is about providing data. SOAP is about verbs, while REST is about nouns. A SOAP service might CalculateTotalSale(); a REST service provides CustomerRecieptNo_12345. The kind of web services architecture you use will depend on the kind of application you’re building. The choice has major implications for the other components of your system.
REST imposes restrictions on what sort of things you can do, because it supports only a handful of actions: GET, POST, PUT, and DELETE. (There are a few other HTTP methods, but these four are the most important.) Fortunately, with these four actions, you can accomplish most basic programming tasks. There’s a close parallel to these actions and create/read/update/delete, or CRUD, the building blocks of data storage systems.
Since the address, or URI, is the primary way to access information in your system, it’s effectively part of your user interface. All the principles of good user interface design apply. So when designing a REST service, you need fine control over the structure of these identifiers.
SOAP, by contrast, typically has just one endpoint. The address itself conveys no information about what services are provided — that’s why SOAP services require a separate WSDL file to tell folks what’s possible. With REST, it should be easy to discover the extent of the system by looking at the URIs alone.
Coming up with good REST URI patterns can be tricky. Using short, descriptive naming conventions for your resources makes them easier to type. But URI patterns must also be distinct and unambiguous.
In the .NET framework, you use the UriTemplate class to define patterns. The UriTemplate implementation that shipped with .NET 3.5 allowed you to define variables that fit into slots in your URI. A typical UriTemplate might look like this: http://restserver/{object}/{id}?view={viewname}.
WCF looks for incoming URIs that match the patterns you define. The pattern defined above would match the following URIs:
http://restserver/customer/5?view=profilehttp://restserver/article/how_to_do_stuff?view=printhttp://restserver/author/John-Smith?view=1Once you’ve defined a UriTemplate, you bind it to a method that has the same number of parameters. (I won’t go into the ABCs of WCF here, but you can check out this MSDN Introduction to WCF if you need a refresher.)
In WCF 3.5, you could only define a variable for a whole segment. A segment is basically the bit between the one forward slash and another, or one querystring parameter. A few bloggers requested more flexibility in UriTemplates, and the WCF team answered with the soon-to-be-released 3.5 SP1. The ability to define variables for partial segments was crucial for our URI design.
Most books about web services, including RESTful Web Services, advocate leaving off file extensions from your URIs. This makes sense for SOAP, where you’re accessing methods and all responses are transmitted in XML. But in REST, you’re serving up items.
In our case, some of these items being served were files and some were records from a database. It seemed inconsistent to have some endpoints that had file extensions and others that didn’t. And we also wanted to be able to serve up different representations for our database records. Our REST service supports both JSON, XML, and HTML. It made sense to use a file extension to distinguish between the different representations.
One workaround would have been to create endpoints like http://restserver/form/1040/xml but that looked funny next to URIs like http://resterver/file/documentation.pdf. True RESTafarians would point out that neither the “/xml” or the “.pdf” are needed, since you can request an appropriate representation using the HTTP ACCEPT header. We decided against the header approach because not all browsers use the ACCEPT HTTP header. Besides, it might be useful for us humans to be able to reach alternate formats by simply changing the URL in the browser address bar.
In WCF 3.5, this required us to create three times the number of endpoints, with a separate method to handle each. We can’t wait for the official release of 3.5 SP1 to make UriTemplates like http://restserver/user/{id}.{ext} possible.
Another source of endpoint duplication was the need to have two different endpoints for http://restserver/folder and http://restserver/folder/. Because the slash is used as a segment delimiter, the dispatcher in WCF 3.5 saw these two URLs as fundamentally different.
So handling what we thought were fairly trivial cases in URI patterns led us to create FIVE TIMES the number of endpoints we wanted. It’s a maintenance nightmare. SP1 can’t get here soon enough.
I finally figured out the source of my HTTP 400 problem. Apparently the Windows Communication Foundation deals with exceptions differently depending on your InstanceContextMode settings. I had been using the Single setting but I should have used the PerCall setting. In PerCall mode, the try/catch block works as expected.
I think it has something to do with the way that WCF distinguishes between channel exceptions and message faults.
Anyway, if you’re building a REST web service, you’ll want to make sure your class is decorated with the following ServiceBehavior attribute.
In part one of this series, I listed several websites and blogs that had useful information on the Windows Communication Foundation (WCF) and REST. I also mentioned that if I was stating again, I’d probably use something other than WCF. Perhaps deriving my own REST server from System.Net.HTTPListener, for example.
Vish asked for some additional details in his comment to that post. He works on the Microsoft WCF development team and was curious about our experience.
I had just begun putting together my response when I noticed Scott Guthrie’s post about Service Pack 1 for the .NET Framework 3.5 beta release. Steve Maine also posted specifics about the ADO.Net Data Services and WCF changes.
So, Vish, it seems your team’s beaten me to the punch on some of these issues! Many of the difficulties I was having with WCF and REST were addressed by the service pack. Here’s an overview of our key stumbling blocks:
I’ll talk about all five of these areas in more detail in upcoming posts in this series. And I’ll be sure check out the SP1 beta once we get our Infovark Alpha release out the door.
As I’ve mentioned previously, I’m someone who likes his code logical and tidy. While I’m just as guilty of playing the F5 game (a.k.a. “try it and see”) as any other developer, it really bothers me when I write code I don’t understand. I’ll spend hours researching a handful of lines of code in a sample posted on someone’s blog. I like to think that it makes me a better programmer. After all, I’ll be in a much better position if I have to write something similar in the future, or to troubleshoot any bugs that appear. And those pesky bugs love hiding in the dark corners of your code.
But that habit of mine can also lead me down some rabbit holes. I’ve given a name to one hole I tumble into on a regular basis. I call it “Fighting the Framework.”
First, a definition. Fighting the Framework occurs whenever you, the programmer, begin second-guessing the code library, development environment, or other tool designed to make your life easier. This second-guessing might happen because you’re convinced that the framework is too heavy, carrying unnecessary baggage when you only need a few lines to handle a particular case. It could happen because the style or idiom of the language is unfamiliar to you. It might be because the framework gets between you and the metal, forcing you to deal with high-level abstractions when you already understand the fundamentals. Whatever the reason, when you’re Fighting the Framework, you’re doing the programming equivalent of swimming upstream. The flow is against you. Everything seems harder than it should.
It’s at this point that I’ll waste hours of time researching alternate frameworks, refactoring already working code, staring off into space, or reading Slashdot. When you see a programmer doing things like this, it’s the equivalent of a child pushing peas around on the dinner plate, trying to find a configuration that tastes better.
Eventually, you just have to accept the fact that every possible configuration of peas on the plate will taste exactly the same — ick — and eat them. Don’t fight the framework. You picked it for a reason. It’s good for you. Perhaps even character building.
I’m in exactly this position with Microsoft .NET right now. Gordon and I picked the Microsoft platform for two solid business reasons:
At the same time, our choice of platform comes with some hefty drawbacks.
Deciding what technologies to use in your product is hard. ReadWriteWeb lists five things to consider when picking a platform. Eric Sink provides guidance about building on solid foundations. Yet despite all the great advice, it isn’t easy to settle on one or two core providers. Especially when you feel you have to accept their entire programming paradigm, warts and all.
In the last two weeks, I’ve dealt with no fewer than three different .NET namespaces that have come up short. I could write several blog articles about what was missing — and probably will at some point — but right now I’ve got to stop dreaming of Rails, Adobe Air, or Google Gears. It’s time to take my own advice: Dean, the grass may be greener on the other side, but for now you’ve still got to mow your patch.
Don’t fight the framework.