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.

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


■
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

target of calls 31
■
Using ClientResource as source of calls 35
Higher-level resources with Java annotations 38
■
Updating the
example mail application 42
2.6 Summary 45
3
Deploying a Restlet application 46
3.1 The purpose of Restlet 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 Spring Framework 63
3.5 Deployment in an existing Java EE server 67
The Servlet extension 67
■
Servlet engine as a connector for a
Restlet component 68

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 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

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
■
Using Java security manager 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 Summary 150
6

7.2 Dealing 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
■
Compressing
representations 186
■
Partial representations 187
Setting cache information 188
■
Conditional methods 190
Removing 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
The JDBC extension 197
■
The Lucene extension 198

8.5 Accessing web APIs from GAE 221
GAE restrictions and URL fetch 221
■
Using Restlet to access
RESTful applications 221
8.6 Accessing OData services 221
What is OData? 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

■
Client-side support 268
Server-side support 271
9.6 Summary 272
10
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 Restlet 286
Exposing RDF resources 286
■
Consuming linked
data with Restlet 291
10.4 Summary 293
11
The future of Restlet 294
11.1 Evolution of HTTP and the rise of SPDY 295
HTTP history so far 295
■

references 415
index 417

xvii
foreword
News flash: the web is kind of a Big Deal.
It is difficult to consider its full impact on technology, society, commerce, education,
governance, and entertainment without resorting to grand language that has been
stated many times before. It is a Big Deal and we will never be the same because of it.
But, here’s the thing. If we sat down and tried to rebuild the web today, knowing
what we know from 20 years of experience with it, we would probably fail. The prob-
lem is that as software developers, we generally think in terms of software constructs:
objects, services, methods, etc. While useful from a solution space perspective, they
can induce coupling and coupling does not scale.
The web works because in its design, Sir Tim Berners-Lee and his cohorts
embraced the notion of change. The thing we forget is that they were not trying to
build the web that we know; they were trying to build a system that worked for a
dynamic organization such as
CERN
. Logically named resources could be requested
and manipulated with no regard to how back-end systems worked. New shapes of
information could be negotiated over time without disrupting deployed systems. Cli-
ents and servers could evolve independently.
The
RE
presentational State Transfer (
REST
) architectural style embraced these
ideas and began to describe how to build flexible, scalable, change-tolerant systems.
The primary shift was away from implementation details and toward the information

CLAP
). He understood the
value of getting the
API
s to a consistent, uniform place before declaring success. The
resulting framework is cleaner, more flexible, and more true to the spirit of
REST
than
any other language-based approach I have seen.
While the Restlet documentation has always been adequate, as I introduced the
API
in my talks and courses, I longed for a solid book on the subject. I even toyed with
the idea of writing one. Thankfully, now, as I look at the manuscript in front of me, I
do not have to.
Restlet in Action by Jérôme et al. is exactly the broad, deep, and example-driven
book I had hoped for. The list of topics they tackle is impressive. The authors provide
thorough but not overwhelming coverage of
REST
itself, security, and performance.
Beyond that, they also discuss issues of growing interest such as mobile applications,
the cloud, the Semantic Web, Linked Data, and the future of
HTTP
. The whole
endeavor is grounded in practical advice on how to use Restlet toward those ends.
These ideas are a Big Deal and this book will help you understand why and how to
benefit from them.
I have already preordered Restlet in Action for many of my clients and students and
anticipate it being a staple in my courses for years to come.
B
RIAN

stay true to the principles of the web, I read more and more about
REST
and the core
HTTP
and
URI
standards and realized that the Servlet
API
had too large a gap apply-
ing those principles. That’s when Restlet emerged as a higher-level Java
API
derived
directly from
REST
and
HTTP
. This was very helpful, so I thought about sharing it
with others. I believed that it could radically change the way we develop web applica-
tions, in the same way that
REST
was radically changing the way I was thinking about
the web.
After announcing the Restlet Framework on December 2005 in an article on
TheServerSide website, I hoped that this open source project, the first
REST
framework
for Java, would contribute to the success of
REST
in the Java world. I wasn’t sure how the
Java community would welcome it since the industry was strongly behind Java

) that would give the community access to the electronic version of the
draft manuscript, and provide us continuous and valuable feedback during the writ-
ing process.
Philippe Mougin, a web services expert, joined us for a few months and contrib-
uted important content on
REST
, including proper
URI
design and a comparison with
the
RPC
style. Also, Bruno Harbulot, a PhD from the University of Manchester who
had been instrumental during the design of the Restlet security
API
, contributed the
initial content for the chapter on security.
Later in 2010, Thierry Templier, a Java
EE
expert and author of several books pub-
lished by Manning, started to collaborate with us on the Restlet project and became
the third coauthor, contributing two chapters on the cloud,
GWT
, and Android, as well
as content on Spring integration,
OSG
i deployment, and security. He is now part of
our team, focusing on the development of our new
APIS
park Platform as a Service
(PaaS) and on editions of the Restlet Framework for JavaScript and

and present committers, as well as users submitting issues, helping with the documen-
tation, and answering questions of other users.
Thanks to Jim Alateras, John D. Mitchell, and Steve Loughran for their help during
the book’s inception phase, especially Guillaume Laforge who introduced us to Manning.
Our sincere thanks to the staff at Manning, including Marjan Bace, Michael
Stephens, Mary Piergies, Maureen Spencer, Christina Rudloff, Corbin Collins, Elizabeth
Martin, Ozren Harlovic, and Melody Dolab. Special thanks to our editor Jeff Bleiel for
his patience and support during the book’s development phase.
Manning rounded up a great group of reviewers, whom we thank for helping to
transform our drafts into the book you are now reading through incremental
enhancements and some refactoring ideas. The reviewers include Adam Taft, Aron
Roberts, Brian Sletten, Bryan Hunt, Colin Yates, Dave Nicolette, Dave Pawson, Doug
Warren, Dustin Jenkins, Fabián Mandelbaum, Gabriel Ciuloaica, Gordon Dickens,
James Ferrans, Jeff Thomas, Jeroen Nouws, Jim Alateras, Johannes Kirschnick, John
Logsdon, Kristoffer Gronowski, Marcelo Ochoa, Rhett Sutphin, Richard E. Brewster,
Stephen Koops, Tal Liron, Vincent Nonnenmacher, and Rob Heittman.
Special thanks to Tim Peierls and Nick Watts, our technical proofreaders, for their
careful review, just before the book went into production, of the chapters and the
ACKNOWLEDGMENTS
xxii
appendixes respectively. Thank you as well to all our
MEAP
readers who posted feed-
back messages on Manning’s Author Online forum; we tried to take all of them into
account. We also thank Brian Sletten for penning the foreword.
Finally, our special thanks go to Benoit Maujean and Stève Sfartz for their continu-
ous support through the years and to our advisory team members, Didier Girard,
Jean-Paul Figer, and Frederic Renouard, for sharing their experience and for helping
us at both the technical and business levels.
JÉRÔME LOUVEL

HTTP
through the use of the Restlet Framework, which directly
derives from those standards.
We’ve tried to stay very practical throughout the book by providing many source
code listings and illustrative figures, introducing Restlet concepts and fundamentals
along the way. In addition, an example
REST
ful mail system serves as a conductor
all along the book.
Six appendixes provide additional details related to the Restlet technology as well
as a generic presentation of the
REST
architecture style and of the
ROA/D
design
methodology that are both valuable beyond the Restlet Framework.
Audience
Our main audience is Java developers who are interested in the web standards such as
HTTP
and
REST
, as well as their usage to expose and consume web
API
s. No prior
knowledge of Restlet is required.
Readers should ideally be familiar with the Java
EE
ecosystem including technolo-
gies such as Servlet,
OSG

virtual machines, configuring virtual hosts and
log and status services using either Java-based or declarative
XML
configuration. It also
covers the deployment in Java
EE
application servers and
OSG
i environments.
Part 2 gets you to the next level of knowledge with more advanced topics such as secu-
rity, documentation, and versioning or optimization. Those topics will become essential
as you move your Restlet application closer to a deployment in production.
Chapter 4 covers producing and consuming
XML
and
JSON
representations, as
well as producing
HTML
using template representations. It explains how
HTTP
con-
tent negotiation is supported by Restlet Framework and describes how to simplify rep-
resentation handling with the converter service.
Chapter 5 covers how to secure a Restlet application at various levels. It starts with
the use of
SSL
/
TLS
to secure communication, then explains how to authenticate