MANNING Jérôme Louvel Thierry Templier Thierry Boileau FOREWORD BY Brian Sletten Developing RESTful web APIs in Java Restlet in Action Restlet in Action D EVELOPING REST FUL WEB API S IN J AVA JÉRÔME LOUVEL THIERRY TEMPLIER THIERRY BOILEAU MANNING S HELTER I SLAND For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 261 Shelter Island, NY 11964 Email: orders@manning.com ©2013 by Manning Publications Co. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps. Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine. Manning Publications Co. Development editor: Jeff Bleiel 20 Baldwin Road Copyeditor: Corbin Collins PO Box 261 Proofreaders: Elizabeth Martin, Melody Dolab Shelter Island, NY 11964 Typesetter: Dennis Dalinnik Cover designer: Marija Tudor ISBN: 9781935182344 Printed in the United States of America 1 2 3 4 5 6 7 8 9 10 – MAL – 18 17 16 15 14 13 12 To my father, Guy Louvel, for his love of life and people and for inspiring my passion for computers —J.L. vii brief contents P ART 1 G ETTING STARTED . 1 1 ■ Introducing the Restlet Framework 3 2 ■ Beginning a Restlet application 13 3 ■ Deploying a Restlet application 46 P ART 2 G ETTING READY TO ROLL OUT 79 4 ■ Producing and consuming Restlet representations 81 5 ■ Securing a Restlet application 121 6 ■ Documenting and versioning a Restlet application 151 7 ■ Enhancing a Restlet application with recipes and best practices 165 P ART 3 F URTHER USE POSSIBILITIES 201 8 ■ Using Restlet with cloud platforms 203 9 ■ Using Restlet in browsers and mobile devices 242 10 ■ Embracing hypermedia and the Semantic Web 274 11 ■ The future of Restlet 294 ix contents foreword xvii preface xix acknowledgments xxi about this book xxiii about the cover illustration xxvii P ART 1 G ETTING 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 [...]... explains how to set up a Restlet application and how the filtering and dispatching of calls works with Restlet s routing system Finally, it covers using client-side and server-side Restlet resources including both method-overriding and annotation-based resource implementation Chapter 3 starts with background information on Restlet components It explains how to deploy in standalone Java SE virtual machines,... Generating classes for access using Restlet 226 Calling OData services 228 ■ ■ 8.7 Accessing Amazon S3 resources Configuring a bucket 230 with the bucket 230 8.8 ■ Accessing Azure services Configuring storage accounts 8.9 230 Accessing a resource 233 233 ■ Using table service Accessing intranet resources with Restlet s SDC extension 235 Secure Data Connector overview 235 Installing SDC agent 236 Using... 88 Using the DOM API 89 Using the SAX API 92 Evaluating XPath expressions 94 Handling XML namespaces 95 Validating against XML schemas 97 Applying XSLT transformations 99 Using the JAXB extension 102 Alternative XML binding extensions 104 ■ ■ ■ ■ ■ 4.3 Producing and consuming JSON representations 105 Using the JSON.org extension Jackson extension 107 4.4 106 Applying template representations Using the... the Restlet SDC connector 238 Restlet SDC support in GAE edition 240 ■ ■ 8.10 Summary 240 233 CONTENTS xiv 9 Using Restlet in browsers and mobile devices 242 9.1 Understanding GWT 243 GWT overview 243 Installing and using GWT 244 GWT and 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... 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 REST and the Semantic Web 280 in representations 281 10.3 11 Summary ■ 286 Consuming linked 293 The future of Restlet 11.1 280 Using RDF Exposing and consuming Linked Data with Restlet Exposing RDF resources 286 data with Restlet 291... extension 111 4.5 Using the ■ Content negotiation 109 ■ 108 Using the 113 Introducing HTTP content negotiation 113 Declaring resource variants 115 Configuring client preferences 116 Combining annotated interfaces and the converter service 117 ■ ■ 4.6 5 Summary 119 Securing a Restlet application 121 5.1 Ensuring transport confidentiality and integrity 122 Understanding TLS and SSL 122 Storing keys and certificates...CONTENTS x 2.3 Setting up a Restlet application 17 Creating an Application subclass 17 Setting application properties 19 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,... Setting up virtual hosting 57 Configuring common services 61 ■ ■ 3.4 Declarative configuration in XML 62 XML configuration with Component 62 with Spring Framework 63 3.5 ■ XML configuration Deployment in an existing Java 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. .. 146 ■ ■ ■ ■ CONTENTS xii 5.5 Ensuring end-to-end integrity of data 147 Ensuring representation integrity 148 Representation digesting 148 Digesting without losing content 149 ■ ■ 5.6 6 Summary 150 Documenting and versioning a Restlet application 151 6.1 The purpose of documentation and versioning Use cases 6.2 6.3 6.4 152 ■ Pitfalls 152 ■ Recommendations 152 153 Introducing WADL 154 The WadlApplication... 156 Improving description of existing server resources 158 Describing a single resource 162 ■ ■ 6.5 6.6 7 Automatic conversion to HTML Summary 164 163 Enhancing a Restlet application with recipes and best practices 165 7.1 Handling common web elements 166 Managing forms 166 Managing cookies 169 Serving file directories 172 Customizing error pages 174 Handling file uploads 176 ■ ■ 7.2 Dealing with Atom . MANNING Jérôme Louvel Thierry Templier Thierry Boileau FOREWORD BY Brian Sletten Developing RESTful web APIs in Java Restlet in Action Restlet in Action D EVELOPING . inspiring my passion for computers —J.L. vii brief contents P ART 1 G ETTING STARTED . 1 1 ■ Introducing the Restlet Framework 3 2 ■ Beginning a Restlet