Restlet in Action Developing RESTful web APIs injava JEROME LOUVEL THIERRY TEMPLIER THIERRY BOILEAU II MANNING Shelter Island
contents foreword xvii preface xix acknowledgments about this book xxi xxiii about the cover illustration xxvii Part 1 Getting started 1 1 Introducing the Restlet Framework 3 1.1 "Hello World" with Restlet 5 Coding a ServerResource subclass 5 Running the server 6 Using the ClientResource class 7 1.2 Overview of the Restlet Framework 8 Main benefits of the Restlet API 9 * Overall design of the Restlet Framework 10 Available editions and deployment targets 11 1.3 Summary 12 2 Beginning a Restlet application 13 2.1 The purpose of Restlet applications 14 2.2 The structure of Restlet applications 15 IX
X CONTENTS 2.3 Setting up a Restlet application 17 Creating an Application subclass 17 * Setting application properties 19 m Exploring the application context 20 Configuring common services 22 2.4 The Restlet routing system 24 Preprocessing and postprocessing calls with a Filter 24 Using a router to dispatch calls based on URIs 27 2.5 Using Restlet resources in an application 30 Resource, the base of all resources 30 Using ServerResource as target of calls 31 Using ClientResource as source of calls 35 Higher-level resources withjava annotations 38 Updating the example mail application 42 2.6 Summary 45 a Restlet application 46 5Deploying 3.1 The purpose ofrestlet components 47 3.2 The structure of Restlet components 48 3.3 Standalone deployment with Java SE 50 Creating a Component subclass 50 * Adding server and client connectors 53* Setting up virtual hosting 57 Configuring common services 61 3.4 Declarative configuration in XML 62 XML configuration with Component 62 XML configuration with SpringFramework 63 3.5 Deployment in an existingjava EE server 67 The Servlet extension 67 Servlet engine as a connector for a Restlet component 68 * Servlet engine as a container of Restlet applications 70 The Oracle XML DB extension 71 Restlet Framework as a library inside Servlet applications 72 Dynamic deployment 3.6 Summary 76 in OSGi environments 73 Part 2 Getting ready to roll otrr 79 A Producing and consuming Restlet representations 81 ' 4.1 Overview of representations 82 The Variant and Representationlnfo base classes 82 The Representation class and its common subclasses 83
CONTENTS 4.2 Producing and consuming XML representations 87 The org.restlet.ext.xml.xmlrepresentation class 88 Using the DOM API 89' Using the SAXAPI 92 Evaluating XPath expressions 94 Handling XML namespaces 95 Validating against XML schemas 97 Applying XSLT transformations 99" Using thejaxb extension 102 m Alternative XML binding extensions 104 4.3 Producing and consumingjson representations 105 UsingtheJSON.org extension 106 Using the Jackson extension 107 4.4 Applying template representations 108 Using the FreeMarker extension 109 Using the Velocity extension 111 4.5 Content negotiation 113 Introducing HTTP content negotiation 113 Declaring resource variants 115 Configuring client preferences 116 Combining annotated interfaces and the converter service 117 4.6 Summary 119 Securing a Restlet application 121 5.1 Ensuring transport confidentiality and integrity 122 Understanding TLS and SSL 122 9 Storing keys and certificates 124 Generating a self-signed certificate 125 Generating a certificate request 125 Importing a trusted certificate 126 * Enabling HTTPS in Restlet 126 Providing a custom SSL context 128 5.2 Authenticating users 129 Providing authentication credentials on the client side 130 The org.restlet.security.authenticatorclass 134 Challenge-based authentication 135 * Verifying user credentials 136 Certificate-based authentication 139 5.3 Assigning roles to authenticated users 141 Request principals 141 The org.restlet.security.enroler interface 142 Organizations, users, and groups 142 The default enroler and verifier 143 5.4 Authorizing user actions 143 The org.restlet.security.authorizer class 143* The role authorizer 144 The method authorizer 145 * Fine-grained authorization 145 * Usingjava security manager 146
. Removing CONTENTS 5.5 Ensuring end-to-end integrity of data 147 Ensuring representation integrity 148 Representation digesting 148 * Digesting-without losing content 149 5.6 Summary 150 Documenting and versioning a Restlet application 151 6.1 The purpose of documentation and versioning 152 Use cases 152 Pitfalls 152 * Recommendations 153 6.2 Introducing WADL 154 6.3 The WadlApplication class 155 6.4 The WadlServerResource class 156 Overview ofproperties and methods 156 Improving description of existing server resources 158 Describing a single resource 162 6.5 Automatic conversion to HTML 163 6.6 Summary 164 ' Enhancing a Restlet application with recipes practices 165 7.1 Handling common web elements 166 7.2 Dealing and best Managingforms 166 * Managing cookies 169 Servingfile directories 172 * Customizing error pages 174 Handling file uploads 176 with Atom and RSS feeds 178 Exposing web feeds 178* Consuming web feeds 180 7.3 Redirecting client calls 180 Manual redirection 181 The org.restlet.redirector class 182 7.4 Improving performances 185 Streaming representations 185 9 Compressing representations 186 Partial representations 187 Setting cache information 188 Conditional methods 190 server-side session state 191 7.5 Modularizing large applications 192 Server dispatcher 192 RIAP pseudoprotocol 194 Private applications 196
" CONTENTS xiii 7.6 Persisting resources state 197 TheJDBC extension 197* The Lucene extension 198 Best design practices 199 7.7 Summary 199 Part 3 Further use possibilities 201 Using Restlet with cloud platforms 203 8.1 Restlet main benefits in the cloud 204 Better SaaS portability 204 * Easy client access to services from the cloud 206 8.2 Deployment in Google App Engine 207 WhatisGAE? 207 * Deploying Restlet applications in GAE 208 Using Google Accounts authentication 210 8.3 Deployment in Amazon Elastic Beanstalk 211 What is Elastic Beanstalk? 211 Deploying Restlet applications 212 8.4 Deployment in Windows Azure 214 What is Azure'? 214 * Deploying Restlet applications 215 8.5 Accessing web APIs from GAE 221 8.6 Accessing GAE restrictions and URL fetch 221 * Using Restlet to access RESTful applications 221 OData services 221 WhatisOData? 222 * Generating classes for access using Restlet 226 * Calling OData services 228 8.7 Accessing Amazon S3 resources 230 Configuring a bucket 230 * Accessing a resource with the bucket 230 8.8 Accessing Azure services 233 Configuring storage accounts 233* Using table service 233 8.9 Accessing intranet resources with Restlet's SDC extension 235 Secure Data Connector overview 235 * Installing SDC agent 236* Using the Restlet SDC connector 238 Restlet SDC support in GAE edition 240 8.10 Summary 240
CONTENTS Using Restlet in browsers and mobile devices 242 9.1 Understanding GWT 243 GWT overview 243 Installing and using GWT 244 GWTand REST 246 9.2 The Restlet edition for GWT 247 The RequestBuilder class of GWT 247 Restlet port to GWT 248 Communicating with a REST API 249 Handling cross-domain requests on the client side 257 9.3 Server-side GWT extension 259 Working along with GWT-RPC 260 Handling cross-domain requests on the server side 261 9.4 Understanding Android 262 Android overview 263 InstallingAndroid and Eclipse plug-ins 263 9.5 The Restlet edition for Android 267 Restlet port to Android 267 m Client-side support 268 Server-side support 271 9.6 Summary 272 Embracing hypermedia and the Semantic Web 274 10.1 Hypermedia as the engine of RESTful web APIs 275 The HATEOAS principle 275 What are hypermedia and hypertext? 276 Hypertext support in Restlet 276 The new hyperdata trend 278 10.2 The Semantic Web with Linked Data 280 REST and the Semantic Web 280 Using RDF in representations 281 10.3 Exposing and consuming Linked Data with Resdet 286 Exposing RDF resources 286 Consuming linked data with Restlet 291 10.4 Summary 293 Thefuture ofrestlet 294 11.1 Evolution of HTTP and the rise of SPDY 295 HTTP history so far 295 Refactoririg with HTTP/1.1 bis 296 The rise of alternatives 296
CONTENTS xv 11.2 The Restlet roadmap 299 Connectorsfor SPDY, HTTPand SIP 299 Enhancements to the Restkt API 299 Editions forfavascript and Dart 301 Restlet Forge 302 Restlet Platform 304 APISpark, the online platformfor web APIs 306 11.3 Restlet community 307 Third-party projects 308 Contributing to Restlet 310 11.4 Summary 310 APPENDIXES 313 appendix A Overview of the Restlet Framework 315 appendix B Installing the RestletFramework 328 appendix C Introducing the REST architecture style 359 appendix D Designing a RESTful web API 371 appendix E MappingREST, HTTP, and the Restlet API 397 appendix F Getting additional help 413 references 415 index 417