RESTful Web Services

✍ Scribed by Richardson, Leonard;Ruby, Sam

• Publisher: O'Reilly Media
• Year: 2007
• Tongue: English
• Leaves: 448
• Category: Library

✦ Synopsis

"Every developer working with the Web needs to read this book." -- David Heinemeier Hansson, creator of the Rails framework

"RESTful Web Services finally provides a practical roadmap for constructing services that embrace the Web, instead of trying to route around it." -- Adam Trachtenberg, PHP author and EBay Web Services Evangelist

You've built web sites that can be used by humans. But can you also build web sites that are usable by machines? That's where the future lies, and that's whatRESTful Web Servicesshows you how to do. The World Wide Web is the most popular distributed application in history, and Web services and mashups have turned it into a powerful distributed computing platform. But today's web service technologies have lost sight of the simplicity that made the Web successful. They don't work like the Web, and they're missing out on its advantages.

This book puts the "Web" back into web services. It shows how you can connect to the programmable web with the technologies you already use every day. The key is REST, the architectural style that drives the Web. This book:


Emphasizes the power of basic Web technologies -- the HTTP application protocol, the URI naming standard, and the XML markup language Introduces the Resource-Oriented Architecture (ROA), a common-sense set of rules for designing RESTful web services Shows how a RESTful design is simpler, more versatile, and more scalable than a design based on Remote Procedure Calls (RPC) Includes real-world examples of RESTful web services, like Amazon's Simple Storage Service and the Atom Publishing Protocol Discusses web service clients for popular programming languages Shows how to implement RESTful services in three popular frameworks -- Ruby on Rails, Restlet (for Java), and Django (for Python) Focuses on practical issues: how to design and implement RESTful web services and clients This is the first book that applies the REST design philosophy to real web services. It sets down the best practices you need to make your design a success, and the techniques you need to turn your design into working code. You can harness the power of the Web for programmable applications: you just have to work with the Web instead of against it. This book shows you how.

✦ Table of Contents

Table of Contents......Page 9
Foreword......Page 13
Preface......Page 15
The Web Is Simple......Page 16
Big Web Services Are Not Simple......Page 17
The Story of the REST......Page 18
What’s in This Book?......Page 20
Administrative Notes......Page 23
Using Code Examples......Page 24
Acknowledgments......Page 25
Chapter 1. The Programmable Web and Its Inhabitants......Page 27
Kinds of Things on the Programmable Web......Page 30
HTTP: Documents in Envelopes......Page 31
Method Information......Page 34
Scoping Information......Page 37
RESTful, Resource-Oriented Architectures......Page 39
RPC-Style Architectures......Page 40
REST-RPC Hybrid Architectures......Page 42
URI......Page 44
WS-*......Page 45
Leftover Terminology......Page 46
Web Services Are Web Sites......Page 49
Wrappers, WADL, and ActiveResource......Page 51
del.icio.us: The Sample Application......Page 52
What the Sample Clients Do......Page 54
Making the Request: HTTP Libraries......Page 55
Optional Features......Page 56
Ruby: rest-open-uri and net/http......Page 57
Python: httplib2......Page 59
Java: HttpClient......Page 60
C#: System.Web.HTTPWebRequest......Page 62
The Command Line: curl......Page 63
Processing the Response: XML Parsers......Page 64
Ruby: REXML, I Guess......Page 66
Python: ElementTree......Page 68
JavaScript: responseXML......Page 69
JSON Parsers: Handling Serialized Data......Page 70
Clients Made Easy with WADL......Page 73
Introducing the Simple Storage Service......Page 75
Object-Oriented Design of S3......Page 76
What If S3 Was a Standalone Library?......Page 77
Resources......Page 78
HTTP Response Codes......Page 80
An S3 Client......Page 81
The Bucket List......Page 82
The Bucket......Page 84
The S3 Object......Page 87
Request Signing and Access Control......Page 90
Signing a URI......Page 94
Setting Access Policy......Page 95
Using the S3 Client Library......Page 96
Clients Made Transparent with ActiveResource......Page 97
Creating a Simple Service......Page 98
An ActiveResource Client......Page 99
A Python Client for the Simple Service......Page 102
Parting Words......Page 103
Resource-Oriented What Now?......Page 105
URIs......Page 107
The Relationship Between URIs and Resources......Page 109
Addressability......Page 110
Statelessness......Page 112
Application State Versus Resource State......Page 116
Representations......Page 117
Deciding Between Representations......Page 118
Links and Connectedness......Page 120
The Uniform Interface......Page 122
HEAD and OPTIONS......Page 123
POST......Page 124
Creating subordinate resources......Page 125
Appending to the resource state......Page 126
Overloaded POST: The not-so-uniform interface......Page 127
Idempotence......Page 128
Why safety and idempotence matter......Page 129
Why the Uniform Interface Matters......Page 130
That’s It!......Page 131
Chapter 5. Designing Read-Only Resource-Oriented Services......Page 133
Resource Design......Page 134
Turning Requirements Into Read-Only Resources......Page 135
Figure Out the Data Set......Page 136
Split the Data Set into Resources......Page 138
Name the Resources......Page 143
No Hierarchy? Use Commas or Semicolons......Page 144
Scale......Page 146
Algorithmic Resource? Use Query Variables......Page 147
Design Your Representations......Page 149
Representing the List of Planets......Page 150
Representing Maps and Points on Maps......Page 152
Representing the Map Tiles......Page 154
Representing Planets and Other Places......Page 156
Representing Lists of Search Results......Page 159
Link the Resources to Each Other......Page 161
What’s Supposed to Happen?......Page 163
Conditional HTTP GET......Page 164
What Might Go Wrong?......Page 165
Conclusion......Page 166
Chapter 6. Designing Read/Write Resource-Oriented Services......Page 169
User Accounts as Resources......Page 170
Why Should User Accounts Be Resources?......Page 171
Authentication, Authorization, Privacy, and Trust......Page 172
Turning Requirements into Read/Write Resources......Page 173
Split the Data Set into Resources......Page 174
Expose a Subset of the Uniform Interface......Page 175
Design the Representation(s) Accepted from the Client......Page 176
Design the Representation(s) to Be Served to the Client......Page 178
Link This Resource to Existing Resources......Page 180
What’s Supposed to Happen?......Page 181
What Might Go Wrong?......Page 182
Split the Data Set into Resources......Page 183
Expose a Subset of the Uniform Interface......Page 184
Design the Representation(s) Accepted from the Client......Page 185
Link This Resource to Existing Resources......Page 187
What’s Supposed to Happen?......Page 190
A Look Back at the Map Service......Page 191
A Social Bookmarking Web Service......Page 193
Figuring Out the Data Set......Page 194
Resource Design......Page 197
REST in Rails......Page 199
The User Controller......Page 200
The Bookmarks Controller......Page 201
The User Tags Controller......Page 203
The Recent Bookmarks Controller......Page 204
Remodeling the REST Way......Page 205
Implementation: The routes.rb File......Page 207
Design the Representation(s) Accepted from the Client......Page 209
Design the Representation(s) Served to the Client......Page 210
Connect Resources to Each Other......Page 211
What’s Supposed to Happen?......Page 212
What Might Go Wrong?......Page 213
Conditional GET......Page 214
The ApplicationController......Page 215
The UsersController......Page 222
The BookmarksController......Page 225
The TagsController......Page 227
The CalendarController......Page 229
The RecentController......Page 230
Model Code......Page 231
The Bookmark Model......Page 232
What Does the Client Need to Know?......Page 235
Natural-Language Service Description......Page 236
Hypermedia Descriptions......Page 238
Resource-Oriented Basics......Page 241
Addressability......Page 242
State and Statelessness......Page 243
The Uniform Interface......Page 244
Safety and Idempotence......Page 245
Overloading POST......Page 246
Why Addressability Matters......Page 247
Why the Uniform Interface Matters......Page 248
Why Connectedness Matters......Page 249
A terrifying example......Page 252
Resource Design......Page 253
Asynchronous Operations......Page 254
Batch Operations......Page 256
Transactions......Page 257
URI Design......Page 259
Incoming Representations......Page 260
Service Versioning......Page 261
Permanent URIs Versus Readable URIs......Page 262
Standard Features of HTTP......Page 263
Basic authentication......Page 264
Digest authentication......Page 265
WSSE username token......Page 267
Compression......Page 269
Conditional GET......Page 270
Please cache......Page 273
Default caching rules......Page 274
Look-Before-You-Leap Requests......Page 275
Partial GET......Page 276
Faking PUT and DELETE......Page 277
The Trouble with Cookies......Page 278
Why Should a User Trust the HTTP Client?......Page 279
Applications with a Web Interface......Page 280
Applications with No Web Interface......Page 281
What Problem Does this Solve?......Page 283
XHTML......Page 285
XHTML with Microformats......Page 287
Atom......Page 289
SVG......Page 291
RDF and RDFa......Page 292
Ad Hoc XHTML......Page 294
Other XML Standards and Ad Hoc Vocabularies......Page 295
Encoding Issues......Page 296
XML and HTTP: Battle of the encodings......Page 297
Prepackaged Control Flows......Page 298
Database-Backed Control Flow......Page 299
POST for creating a new resource......Page 300
Collections......Page 301
Service document......Page 302
Category documents......Page 304
Binary documents as APP members......Page 305
Querying collections......Page 307
Data extensions......Page 308
POST Once Exactly......Page 309
Hypermedia Technologies......Page 310
XHTML 4 links......Page 311
XHTML 4 forms......Page 313
Shortcomings of XHTML 4......Page 314
XHTML 5......Page 315
WADL......Page 316
Describing a del.icio.us resource......Page 317
Describing an APP collection......Page 321
Is WADL evil?......Page 323
Chapter 10. The Resource-Oriented Architecture Versus Big Web Services......Page 325
SOAP......Page 326
The Resource-Oriented Alternative......Page 329
WSDL......Page 330
The Resource-Oriented Alternative......Page 334
The Resource-Oriented Alternative......Page 335
Security......Page 336
Reliable Messaging......Page 337
Transactions......Page 338
BPEL, ESB, and SOA......Page 339
Conclusion......Page 340
From AJAX to Ajax......Page 341
The Ajax Architecture......Page 342
A del.icio.us Example......Page 343
The Advantages of Ajax......Page 346
The Disadvantages of Ajax......Page 347
REST Goes Better......Page 348
Making the Request......Page 349
Handling the Response......Page 350
JSON......Page 351
Don’t Bogart the Benefits of REST......Page 352
Cross-Browser Issues and Ajax Libraries......Page 353
Prototype......Page 355
Dojo......Page 356
Subverting the Browser Security Model......Page 357
Request Proxying......Page 358
JavaScript on Demand......Page 359
Dynamically writing the script tag......Page 361
Library support......Page 362
Ruby on Rails......Page 365
Resources, Controllers, and Views......Page 366
Outgoing Representations......Page 367
Web Applications as Web Services......Page 368
Restlet......Page 369
Basic Concepts......Page 370
Writing Restlet Clients......Page 372
Writing Restlet Services......Page 375
Resource and URI design......Page 376
Request handling and representations......Page 378
Compiling, running, and testing......Page 379
Conclusion......Page 380
Create the Data Model......Page 381
Define Resources and Give Them URIs......Page 382
Implement Resources as Django Views......Page 383
The bookmark list view......Page 384
The bookmark detail view......Page 386
Conclusion......Page 390
HTTP and URI......Page 391
Frameworks for RESTful Development......Page 392
Services You Can Use......Page 393
Read/Write Services......Page 394
Appendix B. The HTTP Response Code Top 42......Page 397
Three to Seven Status Codes: The Bare Minimum......Page 398
101 (“Switching Protocols”)......Page 399
201 (“Created”)......Page 400
205 (“Reset Content”)......Page 401
207 (“Multi-Status”)......Page 402
301 (“Moved Permanently”)......Page 403
303 (“See Other”)......Page 404
305 (“Use Proxy”)......Page 405
4xx: Client-Side Error......Page 406
402 (“Payment Required”)......Page 407
406 (“Not Acceptable”)......Page 408
409 (“Conflict”)......Page 409
411 (“Length Required”)......Page 410
414 (“Request-URI Too Long”)......Page 411
417 (“Expectation Failed”)......Page 412
503 (“Service Unavailable”)......Page 413
505 (“HTTP Version Not Supported”)......Page 414
Appendix C. The HTTP Header Top Infinity......Page 415
Accept-Encoding......Page 416
Allow......Page 417
Connection......Page 418
Content-Length......Page 419
Content-Type......Page 420
Expires......Page 421
If-Match......Page 422
If-Range......Page 423
Location......Page 424
Pragma......Page 425
Range......Page 426
Trailer......Page 427
User-Agent......Page 428
Vary......Page 429
Nonstandard Headers......Page 430
POE-Links......Page 431
X-WSSE......Page 432
Index......Page 435

✦ Subjects

Computer Science;Programming;Science;Technology;Technical;Nonfiction;Software;Internet;Web;Reference;Computers;Architecture