Preface for Effective REST Services via
Preface for Effective REST Services via .NET: For .NET Framework 3.5
Kenn’s Thoughts: The Road to REST, an Engineer’s Tale
It was the spring of 2008, and I had just completed some work for Justin Smith, a senior engineer and connected systems expert at Microsoft. The work involved developing two related Web sites that would consume services offered by a third Web application that would be hosted in something known as the “cloud.” After six weeks of iterative development, we had a set of Web applications that were designed to demonstrate nearly all the ways Web applications can communicate using .NET technologies.
I’d heard about REST, of course, having been fortunate enough to work with Dino Esposito on several of his ASP.NET and AJAX books. Dino is a huge REST proponent. But I admit my background was more along the lines of the SOAP protocol, and I looked at Web services more as remote method calls than creatures of the Internet ecosystem. It didn’t bother me that I needed fancy proxies to communicate with XML-based (and not JSON-based) Web services. I truly hadn’t consciously considered the notion that remote procedure call (RPC) style messaging wasn’t quite architecturally in harmony with the Internet itself.
But I’d had this nagging concern for some time. SOAP and XML-RPC services were becoming very complex, and it seemed that at every turn we were trying to solve some problem that the basic architecture of the Internet presented. Security, streaming large binary objects, browser-based proxies (for AJAX), and so forth were leading to an ever-increasing number of new specifications, each designed to layer more complexity on to what had started as a simple concept. And in most cases, we were trying to bypass the basic workings of the Internet rather than using them to our advantage.
After working with Justin, and after building a very detailed and fully functional set of Web applications that were primarily based on RESTful principles, I found I had drunk from the RESTful Kool-Aid pitcher, and I was stunned by what I had overlooked all of these years. I can remember the epiphany...I literally sat up in my chair, stunned by what I had realized.
What I had overlooked was the simplicity and elegance of the Web’s architecture and design. I had been overcome by the glamour of XML and serializing binary information for transmission in response to requests for actions. I had lost sight of the Internet’s most basic capability of asking for and receiving a resource’s representation. The simplicity and elegance of the Internet struck a new chord with me that day. Even though I had been working with Internet-based technologies for nearly ten years, I found I’d suddenly rediscovered programming for the Internet.
And the simple truth is this is not a bad thing, nor is it uncommon. REST as an architectural concept is precisely in line with the architecture of the Web itself. Any tool you have that can build Web applications can be used to build RESTful services. If you have access to the HTTP method—GET, POST, and so forth—and if you have access to the HTTP headers and entity body, you have all you need to create a RESTful service. Anything else is there only to make creating RESTful services easier by hiding some of the detail. I haven’t had the pleasure of meeting Dr. Roy Fielding, but based on his doctoral dissertation that introduces us all to the concept of REST, I’d hazard a guess that he’d prefer you understand REST at its lowest level before using frameworks that mask the underpinnings. When you do, REST makes perfect sense and things become very clear. Or at least I felt so.
Scott’s Thoughts: REST Is Best
From 2000 until the middle of 2006, I worked at Microsoft on Web services. For four of those years, I worked on Windows Communication Foundation (WCF)—that amazing, transport-agnostic, messaging-unification machine. When WCF finally came out, it supported WS-* and some very basic REST/POX messaging. A few folks on the team were hard at work adding first-class REST support in the form of URI templates and extra functionality for HTTP-hosted services that were later released in .NET 3.5. Why this focus on REST? REST was starting to get very popular, thanks to Roy Fielding’s dissertation. Like many in the Web service community, I read his dissertation many times, trying to really understand what made the Web scale as well as it did. When the WCF 3.5 bits started coming out as previews, I checked out the greatly improved REST support. I was getting excited by what I was seeing and learning. In the broader community and at work, I was finding that people were getting more and more comfortable using HTTP as a communication medium to create, retrieve, update, and delete resources.
I also started seeing the value in easy-to-type URLs. Furthermore, I found that the architecture and code just makes sense to developers. During 2006, I taught several multiday classes on WCF and gave presentations on WCF at a few conferences across the country. My talks on REST were well received. My talks on WCF internals weren’t. People appreciated the elegance of what WCF can do. They just did not see the value in the steep learning curve one had to traverse to master the technology. The thing that pushed me over to REST was the realization of why people were flocking to REST over WS-*. In general, developers used Web browsers and built Web applications long before they ever had to add a service of any kind. REST development builds on what Web developers already know, so there is less to learn. WS-* might be elegant and cover many scenarios, but it does not build on what most developers in most shops across the globe already know.
In the summer of 2008, I joined the development team at MySpace as an architect. Guess what architectural style one of the world’s largest .NET sites uses to handle access to Friends, photo albums, and other resources. Yes, it’s REST. The platform is, first and foremost, a Web platform. REST holds more value for HTTP base endpoints than a WS-* one ever will. REST integrates well with so many other platforms without a whole lot of effort. It doesn’t impose structure on the payload contents—only on the payload metadata. REST is a model that novice developers understand and that expert-level developers can easily manipulate. I love the fact that it is penetrating so much of service development. My day job involves working on OpenSocial—already one of the most successful REST APIs ever developed. Through my work with OpenSocial, I have seen that HTTP and REST compose well with many different security mechanisms. I find it interesting that WS-* protocols compose well with other XML mechanisms. REST composes with other HTTP mechanisms. After spending so many years working with SOAP and other RPC mechanisms, I like what REST has to offer.
How This Book Approaches REST
Today, we use this stuff. We build solutions based on this stuff. We like this stuff. And we’re truly glad to have this book in our hands as architects and developers. Both authors and the entire team behind this book hope you will find it informative and useful as well.
One thing we didn’t want was a 1,000-page monster. When you understand REST, the concept is actually simple, and applying .NET technologies to create RESTful solutions becomes a relatively easy task. If it can’t be explained in a few pages, something’s not right.
The first couple of chapters introduce you to the concepts involved with REST. In a sense, you’re taken back to the earliest days of the Internet to rediscover how the Internet works and how the architectural concept known as REST fits into the Internet ecosystem so well. The first chapter, “RESTful Systems: Back to the Future,” addresses REST itself, and you learn what it means to be RESTful and how to identify behaviors that are not RESTful. Chapter 2, “The HyperText Transfer Protocol and the Universal Resource Identifier,” is devoted to HTTP and the URI. These are the two fundamental tools you’ll work with when developing .NET-based solutions.
Chapters 3 and 4 dig into the client side of the equation. RESTful services are there to serve a client’s needs, and there is no better way to begin to use REST than to consume RESTful services from a client’s perspective. There you learn what works and what doesn’t, with the lessons you learn translating to design principles when you create RESTful services yourself. Chapter 3, “Desktop Client Operations,” shows you how to access RESTful services from desktop applications (both authors believe that the desktop is not a dead platform but is instead enhanced by Internet data and service access), and Chapter 4, “Web Client Operations,” shows you how to access RESTful services from Web-based applications, including Silverlight 2.0. For consistency, both chapters access a single REST service. Later chapters build individual services unique to each chapter to increase the breadth of exposure to different RESTful service implementations.
After you have a feel for how a client might use your service, it’s time to dive into server-side programming. Here the book starts with the basics: what Internet Information Services (IIS) is, how it is put together, and how you use it to implement RESTfu...