General FAQ

Note that there is another FAQ covering more specific questions about the current version of the framework.

Table of contents

  1. Why do I need a framework for REST?
  2. What are the underlying concepts?
  3. What are the advantages of using Restlets instead of Servlets?
  4. I have general questions about REST, where can I get help?
  5. How do you compare to Ruby on Rails?
  6. How do you compare to Django?
  7. What is the link between Restlet and JAX-RS (JSR-311)?

1. Why do I need a framework for REST?

The goal of a framework is to provide a reusable and extendable set of classes and interfaces that will serve as a foundation on which you can construct your own applications more efficiently. The Restlet project was started from the observation that no Java framework was available to help developers build RESTful applications.

First, it's important that you familiarize yourself with the REST architecture style. Then you will realize that the Restlet API derived the name of its classes directly from the REST concepts (resource, representation, connector, component, media type, language, etc.). This means that you are able to think RESTfully and to translate your solution into code more naturally.

If you are not familiar with REST yet, you still gain the protocol abstraction provided by Restlet: the same API is usable for multiple protocols (HTTP server, HTTP client, SMTP client, JDBC client, file system...). For example, you don't need to know the HTTP headers to do content negotiation (see mapping table). Also, you don't need to use and learn multiple APIs (Servlet, HttpUrlConnection and JavaMail for example) to implement standard Web applications.

2. What are the underlying concepts?

As the name of the project implies, the Restlet class is an essential concept to understand. It extends a RESTful Uniform class and serves as the basis for connectors, components, applications, finders, etc. It contains a single "public void handle(Request request, Response)" method which is the contract respected by all parts of the framework.

Then, the Request and Response classes are important as they encapsulate all aspects of a RESTful call, in a protocol neutral way. All REST concepts were implemented, trying to use the REST name as the name of the equivalent Java interface. Some specialized Restlets like Application, Filter, Finder, Router and Route were added to facilitate the processing of calls with URI-based routing or target resource identification.

The processing of REST calls is typically done in two phases. During the first one, the call is processed by a chain of Restlets in order to filter it (like for security purpose or to extract variables from URI parts) to a locate a the target Resource of the call, as identified by the URI. The Finder class is the last Restlet in the processing chain, responsible to actually find a Resource instance based on the processed request information. Once this phase is over, the actual processing can take place in the target Resource class, or more likely one of its subclasses that you will have created. The concepts of Resource and Representation are really central to REST and therefore to the Restlet API. A single Resource can expose several Representations, in different formats, languages, etc. In order to help you return the best Representation of your Resources, an automatic and transparent content negotiation algorithm is used.

3. What are the advantages of using Restlets instead of Servlets?

There are many advantages, but the main one is that Restlet strictly follows the REST architecture style as defined by Roy T. Fielding, co-author of the HTTP protocol. This ensures that your application can easily be developed in a RESTful manner. Each concept of REST has a corresponding Java class in the Restlet API. Also, Restlet removed the concepts of in-memory user sessions which are not RESTful and are a major bottleneck for availability and scalability of Servlet applications.

Another advantage is the ability to work with multiple protocols (HTTP, JDBC, SMTP, etc.) using the exact same API. This is true for both client-side and server-side application. In addition, a Restlet Application can be a client and a server at the same time. It's a truly Web centric framework. If you compare it to the Servlet API, it's an HTTP-only API with support for server-side code. To do client-side code, you need to rely on the low-level HttpURLConnection class from the JDK which uses a completely different API or on the Apache HTTP Client project.

Also, the Restlet API is cleanly separating the low-level protocol aspects from the application aspects. For most applications, you won't need access to HTTP headers to get the media type of a request, you just use request.getEntity().getMediaType(). This separation enables the automatic support of server-side content negotiation, and allows protocol connectors to implement any optimization they need without interfering with the application code. With Servlets, everything is mixed as applications can directly modify the HTTP headers and take control of the output stream.

In addition, via the use of Routers and Routes, the Restlet API gives full control of the call handling to developers. In the Servlet world, the standard approach is to configure the URI mappings in the configuration file of the component, which is not as flexible. There is always the possibility to manually handle the dispatching or to rely on third-party frameworks like Struts or Spring, but it is really not as convenient and powerful as the integrated support provided by the Restlet API.

Finally, the Restlet API is I/O agnostic as its core Representation interface can work equally well with BIO streams (java.io package) and NIO channels (java.nio package). This brings the potential of significant performance boosts when fully NIO compliant connectors will become available. The main advantage will be the increased scalability by removing the need to associate one thread for each opened connection which is a major bottleneck in current Servlet containers.

For those who need to leverage existing Servlet containers or to integrate with larger Servlet applications, there is a light adapter available to let you use the Restlet API as a third-party Servlet library.

4. I have general questions about REST, where can I get help?

There are many resources related to REST that are available on the Web. As it is often hard to find it, we maintain a specialized search engine powered by Google. In addition, here is a selection of popular links:

5. How do you compare to Ruby on Rails?

It is always hard to make fair comparisons, especially when you are from one side and when you don't have an intimate knowledge of the other side. Our general feeling is that Rails was not built with REST principles at its core. Those principles were rather retrofitted in version 2.0. Also, the new support for REST comes with many constraints on the database schema and on the URI namespace.

On the other hand, the Restlet project was explicitly built with REST concepts in mind and has natural support for major features such as transparent content negotiation or automatic support of PUT/DELETE methods when exposing a directory (aka mini-WebDAV mode). Also, you are free to choose any persistence solution for your resources.

6. How do you compare to Django?

Again, it is always hard to make fair comparisons, especially when you are from one side and when you don't have an intimate knowledge of the other side. Our general feeling is that django was not built with REST principles at its core. The project hasn't reach the final 1.0 version yet, but so far there doesn't appear to be any specific REST support even though, as a generic Web framework django can perfectly be used to build RESTful applications.

For example, django doesn't support URI templates natively, you need to manually convert them to Regex expressions. Also, if you want to enable HTTP caching or authentication, you have to manually set the "Last-modified" or "WWW-Authenticate" headers. Like many similar frameworks, it is assumed that you are using a RDBMS to persist your resources which is not the only solution nor the best.

On the other hand, the Restlet project was explicitly built with REST concepts in mind and has natural support for major features such as transparent content negotiation or automatic support of PUT/DELETE methods when exposing a directory (aka mini-WebDAV mode). Also, you are free to choose any persistence solution for your resources.

7. What is the link between Restlet and JAX-RS (JSR-311)?

Restlet is an open source project that provides a complete RESTful framework. When it was launched in 2005, it was the very first framework specifically designed with REST in mind (hence its name). It has its own "Restlet API" which is class-oriented, both client-side and server-side, multi-protocol and with a very broad features scope. It also has an implementation (Noelios Restlet Engine) and a comprehensive set of extension modules. Restlet has even been ported to GWT 1.5 so you can use it right from your browser, without any plugin!

On the other hand, the JAX-RS API (draft state only) is result of the ongoing work of an Expert Group also known as the JSR-311 EG. This effort was initiated and is led by Sun Microsystems, based on an earlier prototype that was part of Sun Web Developer Pack (SWDP) r1 released in 2007. The goal is to produce an API which is annotation-oriented, server-side only and focused on the HTTP protocol. The reference implementation produced by Sun is called Jersey.

To summarize, both APIs have very different designs but are potentially complementary. The good news is that Jérôme Louvel (Restlet's creator) is an active member of the JSR-311 Expert Group and that an implementation of the JAX-RS API was made on top of the Restlet API. This "JAX-RS extension for Restlet" was developed by Stephan Koops in the context of his Master thesis and is one of the most advanced implementations available. For more documentation on this extension, please refer to this page.

Notes

  • Thanks to Dave Pawson for drafting the first version of this FAQ.