About this Book

We wrote this book to help readers efficiently develop RESTful web APIs based on the Restlet Framework. It is also an answer to the open source Restlet community’s request for a comprehensive guide to this technology. The book introduces you to the world of REST and 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 RESTful 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 APIs. No prior knowledge of Restlet is required.

Readers should ideally be familiar with the Java EE ecosystem including technologies such as Servlet, OSGi, and Spring Framework to make the most of the book, but this isn’t a prerequisite to reading the book.

The secondary audience is web API project managers and architects who want to understand how to design and develop a RESTful web API in a controlled manner, using the Restlet Framework or alternative technologies for the implementation.

Roadmap

Part 1 gets you acquainted with the Restlet Framework, quickly looking at the code while introducing important Restlet concepts such as editions, applications, routing, resources, components, and available deployment options.

Chapter 1 gets you started with the Restlet Framework by showing you how to write your first client and server programs. It reviews the main features and benefits of Restlet and gives you an overview of the Restlet Framework, an open source REST framework for Java.

Chapter 2 starts with background information on Restlet applications. It 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, 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 OSGi environments.

Part 2 gets you to the next level of knowledge with more advanced topics such as security, 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 content negotiation is supported by Restlet Framework and describes how to simplify representation 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 remote users, assigning roles in order to authorize them to perform actions on the system. Finally, it describes how to ensure end-to-end integrity of the data.

Chapter 6 explains why you need to document and version your web API and describes the main pitfalls and recommendations for doing so. It introduces the Web Application Description Language (WADL) and its support in Restlet Framework.

Chapter 7 covers handling common web artifacts, such as forms and cookies. It explains how servers can redirect clients and how to handle file uploads on the client and server side. It also provides guidance on how to improve performance of Restlet applications and how to split a large Restlet application into several modules.

Part 3 looks at further Restlet usage possibilities, such as with cloud platforms, browsers, and mobile devices. It also explains how to embrace hypermedia and the Semantic Web in your Restlet projects and what the future of Restlet looks like.

Chapter 8 covers how to use Restlet in the cloud. It starts with deploying Restlet applications to cloud platforms such as Google App Engine, AWS Elastic Beanstalk, and Microsoft Azure. It explains how to access RESTful applications from the cloud using OData, AWS S3, and Azure services and it describes how to securely access intranet resources from public cloud platforms with Restlet, thanks to the Secure Data Connector protocol.

Chapter 9 starts with a description of Restlet editions for GWT and Android. Then it explains how to use REST within GWT applications and within Android-based mobile devices with the Restlet Framework.

Chapter 10 explains why hypermedia is important for RESTful web APIs and describes how hypertext and hyperdata are supported in Restlet to drive applications. In addition, it discusses the relationship between REST and the Semantic Web. Finally, it covers how Restlet can expose and consume Linked Data in RDF.

Chapter 11 starts by covering the state of the HTTP protocol and alternatives. It introduces the SPDY protocol and discusses its impact on REST, HTTP, and Restlet. An overview of the Restlet roadmap covers planned enhancements to Restlet API, extensions, and editions; the planned Restlet Studio tool for Eclipse; and the planned online Restlet Cloud service. It concludes the book with the new “API Spark” platform offering Restlet as a service, as well as a review of Restlet community driven projects.

The book also contains six appendixes. The first gives an overview of the Restlet Framework, its Java API and engine, its available extensions for each edition, and its versioning scheme. The second explains how to install the Restlet Framework using the various distributions provided and the major IDEs available. Appendix C introduces the REST architecture style and how it became an alternative to RPC. Appendix D explains how to design a RESTful web API following the iterative and agile ROA/D methodology in order to succeed in your projects. Appendix E provides reference materials, mapping REST and HTTP to the Java-based Restlet API. The last appendix gives some pointers on where to get additional help beyond this book.

Online and printed references mentioned in the book are listed at the end of the book.

Code conventions and downloads

All source code in the book is in a fixed-width font like this, which sets it off from the surrounding text. In many listings, the code is annotated to point out key concepts, and numbered bullets are sometimes used in the text to provide additional information about the code.

The source code for the examples in the book is available for download from the publisher’s website at www.manning.com/RestletinAction. It is also available for download as part of regular Restlet distributions in the src/org.restlet.example org.restlet.example.book.restlet root package. See the respective chapters for details about the dependencies required to compile and run the examples.

All the source code in the examples has been written for and tested with Restlet Framework version 2.1 and should mostly work with version 2.0 as well, except for features added in version 2.1. The source code should continue to work well with future 2.x releases.

Visit www.restlet.org to download the latest Restlet Framework release. See both chapter 1 and appendix B for more details on how to get started. The only requirement is to have a Java Development Kit (JDK) version 1.5 or above installed on your computer.

Author Online

Purchase of Restlet in Action includes free access to a private web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the authors and from other users. To access the forum and subscribe to it, point your web browser to www.manning.com/RestletinAction. This page provides information on how to get on the forum once you’re registered, what kind of help is available, and the rules of conduct on the forum.

Manning’s commitment to our readers is to provide a venue where a meaningful dialog between individual readers and between readers and the authors can take place. It’s not a commitment to any specific amount of participation on the part of the authors, whose contribution to the AO remains voluntary (and unpaid). We suggest you try asking the authors some challenging questions lest their interest stray!

The Author Online forum and the archives of previous discussions will be accessible from the publisher’s website as long as the book is in print.

About the authors

Jerome Louvel is cofounder and CEO of Restlet Inc. and Restlet SAS, and the creator of the Restlet Framework. Thierry Templier is an R&D architect at Restlet SAS, and a core developer of the Restlet Framework. Thierry Boileau is cofounder of Restlet SAS, an open source community manager, and core developer of the Restlet Framework.