Restlet in Action: Developing RESTful web APIs in Java

Front cover......Page 1
brief contents......Page 8
contents......Page 10
foreword......Page 18
preface......Page 20
acknowledgments......Page 22
Audience......Page 24
Roadmap......Page 25
Code conventions and downloads......Page 26
About the authors......Page 27
about the cover illustration......Page 28
Part 1—Getting started......Page 30
1 Introducing the Restlet Framework......Page 32
1.1.1 Coding a ServerResource subclass......Page 34
1.1.2 Running the server......Page 35
1.1.3 Using the ClientResource class......Page 36
1.2 Overview of the Restlet Framework......Page 37
1.2.1 Main benefits of the Restlet API......Page 38
1.2.2 Overall design of the Restlet Framework......Page 39
1.2.3 Available editions and deployment targets......Page 40
1.3 Summary......Page 41
2 Beginning a Restlet application......Page 42
2.1 The purpose of Restlet applications......Page 43
2.2 The structure of Restlet applications......Page 44
2.3.1 Creating an Application subclass......Page 46
2.3.2 Setting application properties......Page 48
2.3.3 Exploring the application context......Page 49
2.3.4 Configuring common services......Page 51
2.4.1 Preprocessing and postprocessing calls with a Filter......Page 53
2.4.2 Using a router to dispatch calls based on URIs......Page 56
2.5.1 Resource, the base of all resources......Page 59
2.5.2 Using ServerResource as target of calls......Page 60
2.5.3 Using ClientResource as source of calls......Page 64
2.5.4 Higher-level resources with Java annotations......Page 67
2.5.5 Updating the example mail application......Page 71
2.6 Summary......Page 74
3 Deploying a Restlet application......Page 75
3.1 The purpose of Restlet components......Page 76
3.2 The structure of Restlet components......Page 77
3.3.1 Creating a Component subclass......Page 79
3.3.2 Adding server and client connectors......Page 82
3.3.3 Setting up virtual hosting......Page 86
3.3.4 Configuring common services......Page 90
3.4.1 XML configuration with Component......Page 91
3.4.2 XML configuration with Spring Framework......Page 92
3.5.1 The Servlet extension......Page 96
3.5.2 Servlet engine as a connector for a Restlet component......Page 97
3.5.3 Servlet engine as a container of Restlet applications......Page 99
3.5.4 The Oracle XML DB extension......Page 100
3.5.5 Restlet Framework as a library inside Servlet applications......Page 101
3.5.6 Dynamic deployment in OSGi environments......Page 102
3.6 Summary......Page 105
Part 2—Getting ready to roll out......Page 108
4 Producing and consuming Restlet representations......Page 110
4.1.1 The Variant and RepresentationInfo base classes......Page 111
4.1.2 The Representation class and its common subclasses......Page 112
4.2 Producing and consuming XML representations......Page 116
4.2.1 The org.restlet.ext.xml.XmlRepresentation class......Page 117
4.2.2 Using the DOM API......Page 118
4.2.3 Using the SAX API......Page 121
4.2.4 Evaluating XPath expressions......Page 123
4.2.5 Handling XML namespaces......Page 124
4.2.6 Validating against XML schemas......Page 126
4.2.7 Applying XSLT transformations......Page 128
4.2.8 Using the JAXB extension......Page 131
4.2.9 Alternative XML binding extensions......Page 133
4.3 Producing and consuming JSON representations......Page 134
4.3.1 Using the JSON.org extension......Page 135
4.3.2 Using the Jackson extension......Page 136
4.4 Applying template representations......Page 137
4.4.1 Using the FreeMarker extension......Page 138
4.4.2 Using the Velocity extension......Page 140
4.5.1 Introducing HTTP content negotiation......Page 142
4.5.2 Declaring resource variants......Page 144
4.5.3 Configuring client preferences......Page 145
4.5.4 Combining annotated interfaces and the converter service......Page 146
4.6 Summary......Page 148
5 Securing a Restlet application......Page 150
5.1.1 Understanding TLS and SSL......Page 151
5.1.2 Storing keys and certificates......Page 153
5.1.4 Generating a certificate request......Page 154
5.1.6 Enabling HTTPS in Restlet......Page 155
5.1.7 Providing a custom SSL context......Page 157
5.2 Authenticating users......Page 158
5.2.1 Providing authentication credentials on the client side......Page 159
5.2.2 The org.restlet.security.Authenticator class......Page 163
5.2.3 Challenge-based authentication......Page 164
5.2.4 Verifying user credentials......Page 165
5.2.5 Certificate-based authentication......Page 168
5.3.1 Request principals......Page 170
5.3.3 Organizations, users, and groups......Page 171
5.4.1 The org.restlet.security.Authorizer class......Page 172
5.4.2 The role authorizer......Page 173
5.4.4 Fine-grained authorization......Page 174
5.4.5 Using Java security manager......Page 175
5.5 Ensuring end-to-end integrity of data......Page 176
5.5.2 Representation digesting......Page 177
5.5.3 Digesting without losing content......Page 178
5.6 Summary......Page 179
6 Documenting and versioning a Restlet application......Page 180
6.1.2 Pitfalls......Page 181
6.1.3 Recommendations......Page 182
6.2 Introducing WADL......Page 183
6.3 The WadlApplication class......Page 184
6.4.1 Overview of properties and methods......Page 185
6.4.2 Improving description of existing server resources......Page 187
6.4.3 Describing a single resource......Page 191
6.5 Automatic conversion to HTML......Page 192
6.6 Summary......Page 193
7 Enhancing a Restlet application with recipes and best practices......Page 194
7.1.1 Managing forms......Page 195
7.1.2 Managing cookies......Page 198
7.1.3 Serving file directories......Page 201
7.1.4 Customizing error pages......Page 203
7.1.5 Handling file uploads......Page 205
7.2.1 Exposing web feeds......Page 207
7.3 Redirecting client calls......Page 209
7.3.1 Manual redirection......Page 210
7.3.2 The org.restlet.Redirector class......Page 211
7.4.1 Streaming representations......Page 214
7.4.2 Compressing representations......Page 215
7.4.3 Partial representations......Page 216
7.4.4 Setting cache information......Page 217
7.4.5 Conditional methods......Page 219
7.4.6 Removing server-side session state......Page 220
7.5.1 Server dispatcher......Page 221
7.5.2 RIAP pseudoprotocol......Page 223
7.5.3 Private applications......Page 225
7.6.1 The JDBC extension......Page 226
7.6.2 The Lucene extension......Page 227
7.7 Summary......Page 228
Part 3—Further use possibilities......Page 230
8 Using Restlet with cloud platforms......Page 232
8.1.1 Better SaaS portability......Page 233
8.1.2 Easy client access to services from the cloud......Page 235
8.2.1 What is GAE?......Page 236
8.2.2 Deploying Restlet applications in GAE......Page 237
8.2.3 Using Google Accounts authentication......Page 239
8.3.1 What is Elastic Beanstalk?......Page 240
8.3.2 Deploying Restlet applications......Page 241
8.4.1 What is Azure?......Page 243
8.4.2 Deploying Restlet applications......Page 244
8.6 Accessing OData services......Page 250
8.6.1 What is OData?......Page 251
8.6.2 Generating classes for access using Restlet......Page 255
8.6.3 Calling OData services......Page 257
8.7.2 Accessing a resource with the bucket......Page 259
8.8.2 Using table service......Page 262
8.9.1 Secure Data Connector overview......Page 264
8.9.2 Installing SDC agent......Page 265
8.9.3 Using the Restlet SDC connector......Page 267
8.10 Summary......Page 269
9 Using Restlet in browsers and mobile devices......Page 271
9.1.1 GWT overview......Page 272
9.1.2 Installing and using GWT......Page 273
9.1.3 GWT and REST......Page 275
9.2.1 The RequestBuilder class of GWT......Page 276
9.2.2 Restlet port to GWT......Page 277
9.2.3 Communicating with a REST API......Page 278
9.2.4 Handling cross-domain requests on the client side......Page 286
9.3 Server-side GWT extension......Page 288
9.3.1 Working along with GWT-RPC......Page 289
9.3.2 Handling cross-domain requests on the server side......Page 290
9.4 Understanding Android......Page 291
9.4.2 Installing Android and Eclipse plug-ins......Page 292
9.5.1 Restlet port to Android......Page 296
9.5.2 Client-side support......Page 297
9.5.3 Server-side support......Page 300
9.6 Summary......Page 301
10 Embracing hypermedia and the Semantic Web......Page 303
10.1.1 The HATEOAS principle......Page 304
10.1.3 Hypertext support in Restlet......Page 305
10.1.4 The new hyperdata trend......Page 307
10.2.1 REST and the Semantic Web......Page 309
10.2.2 Using RDF in representations......Page 310
10.3.1 Exposing RDF resources......Page 315
10.3.2 Consuming linked data with Restlet......Page 320
10.4 Summary......Page 322
11 The future of Restlet......Page 323
11.1.1 HTTP history so far......Page 324
11.1.3 The rise of alternatives......Page 325
11.2.2 Enhancements to the Restlet API......Page 328
11.2.3 Editions for JavaScript and Dart......Page 330
11.2.4 Restlet Forge......Page 331
11.2.5 Restlet Platform......Page 333
11.2.6 APISpark, the online platform for web APIs......Page 335
11.3 Restlet community......Page 336
11.3.1 Third-party projects......Page 337
11.4 Summary......Page 339
appendixes......Page 342
A.1 Restlet API......Page 344
A.1.1 Root package......Page 345
A.1.2 Data package......Page 346
A.1.4 Resource package......Page 347
A.1.6 Security package......Page 348
A.1.8 Util package......Page 349
A.3 Extensions......Page 350
A.4.1 Edition for Java SE......Page 351
A.4.5 Edition for Google Web Toolkit......Page 352
A.4.7 Matrix of extensions per edition......Page 353
A.5.1 Logical versions......Page 355
A.5.2 Versioning scheme......Page 356
B.1.1 Maven repository......Page 357
B.1.2 Zip files......Page 359
B.1.4 Eclipse update site......Page 360
B.2 Setting up your IDE......Page 363
B.2.1 Eclipse......Page 365
B.2.2 NetBeans......Page 372
B.2.3 IntelliJ IDEA......Page 374
B.2.4 Command line......Page 378
B.3.1 Unit testing......Page 379
B.3.2 Integration testing......Page 384
B.3.3 Debugging problems......Page 386
C.1 Supporting all web features with REST......Page 388
C.1.1 The all-embracing web......Page 389
C.1.2 How REST explains the architecture elements of the web......Page 390
C.1.3 Understanding the relationship between REST and HTTP......Page 394
C.2 How REST became an alternative to RPC......Page 395
appendix D Designing a RESTful web API......Page 400
D.1.1 Introducing Resource-Oriented Analysis & Design (ROA/D)......Page 401
D.1.4 Constructing the solution......Page 404
D.2.1 Collecting requirements from the sources......Page 405
D.2.2 Classifying requirements by priority......Page 406
D.3 Analyzing requirements......Page 407
D.3.2 Defining the domain model......Page 408
D.4 Designing the solution......Page 410
D.4.1 Defining the logical architecture......Page 411
D.4.2 Deriving the resource model......Page 413
D.4.3 Identifying and classifying the resources......Page 414
D.4.4 Defining the URI space......Page 416
D.4.5 Defining allowed methods......Page 419
D.4.6 Defining response statuses......Page 422
D.4.7 Defining representation classes......Page 423
E.1 Mapping REST concepts to Restlet classes......Page 426
E.2 Mapping HTTP concepts to Restlet classes......Page 427
E.3 Mapping HTTP headers to Restlet properties......Page 428
E.4 Available connectors......Page 434
E.5 Available converters......Page 435
E.6 Supported security challenge schemes......Page 439
E.7 Scheme authorities of RIAP and CLAP pseudoprotocols......Page 440
F.1 Accessing online documentation......Page 442
F.4 Professional services......Page 443
references......Page 444
For further reading......Page 445
A......Page 446
C......Page 447
D......Page 449
G......Page 450
H......Page 451
J......Page 452
M......Page 453
O......Page 454
P......Page 455
R......Page 456
S......Page 458
T......Page 459
X......Page 460
Z......Page 461
Back cover......Page 462