REST in Practice Jim Webber, Savas Parastatidis, and Ian Robinson Beijing · Cambridge · Farnham · Köln · Sebastopol · Tokyo REST in Practice by Jim Webber, Savas Parastatidis, and Ian Robinson Copyright © 2010 Jim Webber, Savas Parastatidis, and Ian Robinson. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected]. Editor: Simon St.Laurent Indexer: Lucie Haskins Production Editor: Rachel Monaghan Cover Designer: Karen Montgomery Copyeditor: Audrey Doyle Interior Designer: Ron Bilodeau Proofreader: Rachel Monaghan Illustrator: Robert Romano Production Services: Newgen North America Printing History: September 2010: First Edition. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc., REST in Practice, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and au- thors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. ISBN: 978-0-596-80582-1 [M] C o n t e n t s Foreword .. ............................ ix Preface .. ............................. xi 1 The Web As a Platform for Building Distributed Systems .. 1 Architecture of the Web 2 Thinking in Resources 4 From the Web Architecture to the REST Architectural Style 12 The Web As an Application Platform 15 Web Friendliness and the Richardson Maturity Model 18 GET on Board 20 2 Introducing Restbucks: How to GET a Coffee, Web Style .. ........................... 21 Restbucks: A Little Coffee Shop with Global Ambitions 22 Toolbox 27 Here Comes the Web 30 3 Basic Web Integration .. ................... 31 Lose Weight, Feel Great! 31 A Simple Coffee Ordering System 32 URI Templates 35 URI Tunneling 37 POX: Plain Old XML over HTTP 42 We Are Just Getting Started 54 4 CRUD Web Services .. .................... 55 Modeling Orders As Resources 55 Building CRUD Services 57 Aligning Resource State 78 Consuming CRUD Services 83 Consuming Services Automatically with WADL 86 CRUD Is Good, but It’s Not Great 90 v 5 Hypermedia Services .. .................... 93 The Hypermedia Tenet 93 Hypermedia Formats 97 Contracts 108 Hypermedia Protocols 112 Implementing a Hypermedia Service 128 Building the Ordering Service in Java 128 Building the Ordering Service in .NET 140 Ready, Set, Action 152 6 Scaling Out .. ..........................155 GET Back to Basics 155 Caching 157 Making Content Cacheable 161 Implementing Caching in .NET 167 Consistency 171 Extending Freshness 179 Stay Fresh 183 7 The Atom Syndication Format .. ...............185 The Format 185 Common Uses for Atom 188 Using Atom for Event-Driven Systems 189 Building an Atom Service in Java 207 Building an Atom Service in .NET 219 Atom Everywhere? 234 After the Event 236 8 Atom Publishing Protocol .. 237 Atom Publishing Protocol 238 Implementing Order Fulfillment Using AtomPub 249 Implementing AtomPub in .NET 268 A Versatile Protocol 283 9 Web Security .. .........................285 HTTP Security Essentials 286 Identity and the OpenID Protocol 295 The OAuth Protocol 315 Service Hacks and Defenses 339 Final Thoughts 349 vi Contents 10 Semantics .. ..........................351 Syntax Versus Semantics 351 Structure and Representation of Information 352 The Semantic Web 357 Microformats 372 Linked Data and the Web 373 Guidance 374 11 The Web and WS-*. 375 Are Web Services Evil? 375 SOAP: The Whole Truth 376 WSDL: Just Another Object IDL 380 Two Wrongs Don’t Make a Right 386 Secure, Reliable, Transacted 387 A Requiem for Web Services? 405 12 Building the Case for the Web .. ..............407 No More Silver Bullets 407 Building and Running Web-Based Services 407 No Architecture Without Measurement 409 Selling the Web 412 Go Forth and Build 414 Index .. ..............................415 Contents vii Chapter one The Web As a Platform for Building Distributed Systems The Web haS radically trAnsformed thE way we produce and share informa- tion. Its international ecosystem of applications and services allows us to search, aggre- gate, combine, transform, replicate, cache, and archive the information that underpins today’s digital society. Successful despite its chaotic growth, it is the largest, least formal integration project ever attempted—all of this, despite having barely entered its teenage years. Today’s Web is in large part the human Web: human users are the direct consumers of the services offered by the majority of today’s web applications. Given its success in managing our digital needs at such phenomenal scale, we’re now starting to ask how we might apply the Web’s underlying architectural principles to building other kinds of distributed systems, particularly the kinds of distributed systems typically implemented by “enterprise application” developers. Why is the Web such a successful application platform? What are its guiding principles, and how should we apply them when building distributed systems? What technologies can and should we use? Why does the Web model feel familiar, but still different from previous platforms? Conversely, is the Web always the solution to the challenges we face as enterprise application developers? These are the questions we’ll answer in the rest of this book. Our goal throughout is to describe how to build distributed systems based on the Web’s architecture. We show how to implement systems that use the Web’s predominant application protocol, 1 HyperText Transfer Protocol (HTTP), and which leverage REST’s architectural tenets. We explain the Web’s fundamental principles in simple terms and discuss their relevance in developing robust distributed applications. And we illustrate all this with challenging examples drawn from representative enterprise scenarios and solutions implemented using Java and .NET. The remainder of this chapter takes a first, high-level look at the Web’s architecture. Here we discuss some key building blocks, touch briefly on the REpresentational State Transfer (REST) architectural style, and explain why the Web can readily be used as a platform for connecting services at global scale. Subsequent chapters dive deeper into the Web’s principles and discuss the technologies available for connecting systems in a web-friendly manner. Architecture of the Web Tim Berners-Lee designed and built the foundations of the World Wide Web while a research fellow at CERN in the early 1990s. His motivation was to create an easy-to- use, distributed, loosely coupled system for sharing documents. Rather than starting from traditional distributed application middleware stacks, he opted for a small set of technologies and architectural principles. His approach made it simple to imple- ment applications and author content. At the same time, it enabled the nascent Web to scale and evolve globally. Within a few years of the Web’s birth, academic and research websites had emerged all over the Internet. Shortly thereafter, the busi- ness world started establishing a web presence and extracting web-scale profits from its use. Today the Web is a heady mix of business, research, government, social, and individual interests. This diverse constituency makes the Web a chaotic place—the only consistency being the consistent variety of the interests represented there; the only unifying factor the seemingly never-ending thread of connections that lead from gaming to commerce, to dating to enterprise administration, as we see in Figure 1-1. Despite the emergent chaos at global scale, the Web is remarkably simple to under- stand and easy to use at local scale. As documented by the World Wide Web Consortium (W3C) in its “Architecture of the World Wide Web,” the anarchic architecture of today’s Web is the culmination of thousands of simple, small-scale interactions between agents and resources that use the founding technologies of HTTP and the URI.* * “Architecture of the World Wide Web, Volume One,” http://www.w3.org/TR/webarch/. 2 CHAPTER 1: the web as A platform for Building DISTRIButeD SYSTEMS Figure 1-1. the Web The Web’s architecture, as portrayed in Figure 1-1, shows URIs and resources playing a leading role, supported by web caches for scalability. Behind the scenes, service bound- aries support isolation and independent evolution of functionality, thereby encourag- ing loose coupling. In the enterprise, the same architectural principles and technology can be applied. Architecture OF THE Web 3 Traditionally we’ve used middleware to build distributed systems. Despite the amount of research and development that has gone into such platforms, none of them has managed to become as pervasive as the Web is today. Traditional middleware tech- nologies have always focused on the computer science aspects of distributed systems: components, type systems, objects, remote procedure calls, and so on. The Web’s middleware is a set of widely deployed and commoditized servers. From