www.allitebooks.com www.allitebooks.com RESTful Web Services Cookbook www.allitebooks.com www.allitebooks.com RESTful Web Services Cookbook Subbu Allamaraju Beijing • Cambridge • Farnham • Köln • Sebastopol • Taipei • Tokyo www.allitebooks.com RESTful Web Services Cookbook by Subbu Allamaraju Copyright © 2010 Yahoo!, Inc. 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: Mary E. Treseler Cover Designer: Karen Montgomery Production Editor: Sumita Mukherji Interior Designer: David Futato Production Services: Molly Sharp Illustrator: Robert Romano Printing History: March 2010: First Edition. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. RESTful Web Services Cookbook, the image of a great fringed lizard, 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 author assume no responsibility for errors or omissions, or for damages resulting from the use of the information con- tained herein. TM This book uses RepKover™, a durable and flexible lay-flat binding. ISBN: 978-0-596-80168-7 [M] 1266619255 www.allitebooks.com Table of Contents Preface . ix 1. Using the Uniform Interface . 1 1.1 How to Keep Interactions Visible 2 1.2 When to Trade Visibility 4 1.3 How to Maintain Application State 7 1.4 How to Implement Safe and Idempotent Methods on the Server 9 1.5 How to Treat Safe and Idempotent Methods in Clients 12 1.6 When to Use GET 13 1.7 When to Use POST 14 1.8 How to Create Resources Using POST 16 1.9 When to Use PUT to Create New Resources 18 1.10 How to Use POST for Asynchronous Tasks 19 1.11 How to Use DELETE for Asynchronous Deletion 23 1.12 When to Use Custom HTTP Methods 23 1.13 When and How to Use Custom HTTP Headers 25 2. Identifying Resources . 29 2.1 How to Identify Resources from Domain Nouns 30 2.2 How to Choose Resource Granularity 31 2.3 How to Organize Resources into Collections 32 2.4 When to Combine Resources into Composites 34 2.5 How to Support Computing/Processing Functions 37 2.6 When and How to Use Controllers to Operate on Resources 39 3. Designing Representations . 45 3.1 How to Use Entity Headers to Annotate Representations 46 3.2 How to Interpret Entity Headers 49 3.3 How to Avoid Character Encoding Mismatch 50 3.4 How to Choose a Representation Format and a Media Type 52 3.5 How to Design XML Representations 56 v www.allitebooks.com 3.6 How to Design JSON Representations 58 3.7 How to Design Representations of Collections 59 3.8 How to Keep Collections Homogeneous 61 3.9 How to Use Portable Data Formats in Representations 62 3.10 When to Use Entity Identifiers 65 3.11 How to Encode Binary Data in Representations 66 3.12 When and How to Serve HTML Representations 67 3.13 How to Return Errors 69 3.14 How to Treat Errors in Clients 73 4. Designing URIs . 75 4.1 How to Design URIs 75 4.2 How to Use URIs As Opaque Identifiers 79 4.3 How to Let Clients Treat URIs As Opaque Identifiers 81 4.4 How to Keep URIs Cool 83 5. Web Linking . 87 5.1 How to Use Links in XML Representations 88 5.2 How to Use Links in JSON Representations 90 5.3 When and How to Use Link Headers 91 5.4 How to Assign Link Relation Types 93 5.5 How to Use Links to Manage Application Flow 95 5.6 How to Deal with Ephemeral URIs 99 5.7 When and How to Use URI Templates 101 5.8 How to Use Links in Clients 103 6. Atom and AtomPub . 107 6.1 How to Model Resources Using Atom 108 6.2 When to Use Atom 111 6.3 How to Use AtomPub Service and Category Documents 116 6.4 How to Use AtomPub for Feed and Entry Resources 118 6.5 How to Use Media Resources 119 7. Content Negotiation . 123 7.1 How to Indicate Client Preferences 124 7.2 How to Implement Media Type Negotiation 126 7.3 How to Implement Language Negotiation 127 7.4 How to Implement Character Encoding Negotiation 129 7.5 How to Support Compression 130 7.6 When and How to Send the Vary Header 131 7.7 How to Handle Negotiation Failures 132 7.8 How to Use Agent-Driven Content Negotiation 133 7.9 When to Support Server-Driven Negotiation 135 vi | Table of Contents www.allitebooks.com 8. Queries . 137 8.1 How to Design URIs for Queries 138 8.2 How to Design Query Responses 140 8.3 How to Support Query Requests with Large Inputs 142 8.4 How to Store Queries 144 9. Web Caching . 147 9.1 How to Set Expiration Caching Headers 148 9.2 When to Set Expiration Caching Headers 151 9.3 When and How to Use Expiration Headers in Clients 153 9.4 How to Support Caching for Composite Resources 154 9.5 How to Keep Caches Fresh and Warm 156 10. Conditional Requests . 159 10.1 How to Generate Last-Modified and ETag Headers 161 10.2 How to Implement Conditional GET Requests in Servers 162 10.3 How to Submit Conditional GET and HEAD Requests from Clients 165 10.4 How to Implement Conditional PUT Requests in Servers 167 10.5 How to Implement Conditional DELETE Requests in Servers 171 10.6 How to Make Unconditional GET Requests from Clients 172 10.7 How to Submit Conditional PUT and DELETE Requests from Clients 174 10.8 How to Make POST Requests Conditional 176 10.9 How to Generate One-Time URIs 179 11. Miscellaneous Writes . 183 11.1 How to Copy a Resource 184 11.2 How to Merge Resources 186 11.3 How to Move a Resource 188 11.4 When to Use WebDAV Methods 189 11.5 How to Support Operations Across Servers 191 11.6 How to Take Snapshots of Resources 193 11.7 How to Undo Resource Updates 196 11.8 How to Refine Resources for Partial Updates 198 11.9 How to Use the PATCH Method 201 11.10 How to Process Similar Resources in Bulk 203 11.11 How to Trigger Bulk Operations 206 11.12 When to Tunnel Multiple Requests Using POST 208 11.13 How to Support Batch Requests 211 11.14 How to Support Transactions 213 Table of Contents | vii www.allitebooks.com 12. Security . 217 12.1 How to Use Basic Authentication to Authenticate Clients 218 12.2 How to Use Digest Authentication to Authenticate Clients 221 12.3 How to Use Three-Legged OAuth 223 12.4 How to Use Two-Legged OAuth 228 12.5 How to Deal with Sensitive Information in URIs 231 12.6 How to Maintain the Confidentiality and Integrity of Representations 233 13. Extensibility and Versioning . 235 13.1 How to Maintain URI Compatibility 236 13.2 How to Maintain Compatibility of XML and JSON Representations 237 13.3 How to Extend Atom 241 13.4 How to Maintain Compatibility of Links 244 13.5 How to Implement Clients to Support Extensibility 246 13.6 When to Version 247 13.7 How to Version RESTful Web Services 248 14. Enabling Discovery . 251 14.1 How to Document RESTful Web Services 251 14.2 How to Use OPTIONS 254 A. Additional Reading . 257 B. Overview of REST . 261 C. HTTP Methods . 265 D. Atom Syndication Format . 271 E. Link Relation Registry . 277 Index . 285 viii | Table of Contents www.allitebooks.com Preface In 2000, Roy Fielding, one of the key contributors to HTTP and URI, codified the architecture of the Web in his doctoral thesis titled “Architectural Styles and the Design of Network-Based Software Architectures.” In this thesis, he introduced an architecture style known as Representational State Transfer (REST). This style, in abstract terms, describes the foundation of the World Wide Web. The technologies that make up this foundation include the Hypertext Transfer Protocol (HTTP), Uniform Resource Iden- tifier (URI), markup languages such as HTML and XML, and web-friendly formats such as JSON. REST is an architectural style for networked applications. It consists of several con- straints to address separation of concerns, visibility, reliability, scalability, perform- ance, etc. See Appendix B for a brief overview of these constraints. What makes REST attractive to build distributed and decentralized client/server applications is the infra- structure of the Web. Deploying web services on this infrastructure lets you take advantage of a wide range of existing infrastructure that includes web servers, client libraries, proxy servers, caches, firewalls, and so on. Although, in theory, it is possible to build RESTful applications without relying on HTTP, attempting to do so can be an expensive proposition. In this book, RESTful web services means web services built using HTTP, URIs, XML, JSON, Atom, etc.