Restlet in Action. Developing RESTful web APIs injava JEROME LOUVEL MANNING THIERRY TEMPLIER THIERRY BOILEAU. Shelter Island

Transcription

1 Restlet in Action Developing RESTful web APIs injava JEROME LOUVEL THIERRY TEMPLIER THIERRY BOILEAU II MANNING Shelter Island

2 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 "Hello World" with Restlet 5 Coding a ServerResource subclass 5 Running the server 6 Using the ClientResource class 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 Summary 12 2 Beginning a Restlet application The purpose of Restlet applications The structure of Restlet applications 15 IX

3 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 The Restlet routing system 24 Preprocessing and postprocessing calls with a Filter 24 Using a router to dispatch calls based on URIs 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 Summary 45 a Restlet application 46 5Deploying 3.1 The purpose ofrestlet components The structure of Restlet components 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 Declarative configuration in XML 62 XML configuration with Component 62 XML configuration with SpringFramework 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

4 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 Producing and consumingjson representations 105 UsingtheJSON.org extension 106 Using the Jackson extension Applying template representations 108 Using the FreeMarker extension 109 Using the Velocity extension Content negotiation 113 Introducing HTTP content negotiation 113 Declaring resource variants 115 Configuring client preferences 116 Combining annotated interfaces and the converter service Summary 119 Securing a Restlet application Ensuring transport confidentiality and integrity 122 Understanding TLS and SSL 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 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 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 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

5 . Removing CONTENTS 5.5 Ensuring end-to-end integrity of data 147 Ensuring representation integrity 148 Representation digesting 148 * Digesting-without losing content Summary 150 Documenting and versioning a Restlet application The purpose of documentation and versioning 152 Use cases 152 Pitfalls 152 * Recommendations Introducing WADL The WadlApplication class The WadlServerResource class 156 Overview ofproperties and methods 156 Improving description of existing server resources 158 Describing a single resource Automatic conversion to HTML Summary 164 ' Enhancing a Restlet application with recipes practices Handling common web elements 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 Redirecting client calls 180 Manual redirection 181 The org.restlet.redirector class Improving performances 185 Streaming representations Compressing representations 186 Partial representations 187 Setting cache information 188 Conditional methods 190 server-side session state Modularizing large applications 192 Server dispatcher 192 RIAP pseudoprotocol 194 Private applications 196

6 " CONTENTS xiii 7.6 Persisting resources state 197 TheJDBC extension 197* The Lucene extension 198 Best design practices Summary 199 Part 3 Further use possibilities 201 Using Restlet with cloud platforms Restlet main benefits in the cloud 204 Better SaaS portability 204 * Easy client access to services from the cloud Deployment in Google App Engine 207 WhatisGAE? 207 * Deploying Restlet applications in GAE 208 Using Google Accounts authentication Deployment in Amazon Elastic Beanstalk 211 What is Elastic Beanstalk? 211 Deploying Restlet applications Deployment in Windows Azure 214 What is Azure'? 214 * Deploying Restlet applications Accessing web APIs from GAE 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 Accessing Amazon S3 resources 230 Configuring a bucket 230 * Accessing a resource with the bucket Accessing Azure services 233 Configuring storage accounts 233* Using table service 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 Summary 240

7 CONTENTS Using Restlet in browsers and mobile devices Understanding GWT 243 GWT overview 243 Installing and using GWT 244 GWTand REST 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 Server-side GWT extension 259 Working along with GWT-RPC 260 Handling cross-domain requests on the server side Understanding Android 262 Android overview 263 InstallingAndroid and Eclipse plug-ins The Restlet edition for Android 267 Restlet port to Android 267 m Client-side support 268 Server-side support Summary 272 Embracing hypermedia and the Semantic Web 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 The Semantic Web with Linked Data 280 REST and the Semantic Web 280 Using RDF in representations Exposing and consuming Linked Data with Resdet 286 Exposing RDF resources 286 Consuming linked data with Restlet Summary 293 Thefuture ofrestlet 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

8 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 Restlet community 307 Third-party projects 308 Contributing to Restlet 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