Chapter 6. Documenting and versioning a Restlet application

Now that you’ve seen how to secure Restlet applications, it’s time to continue your exploration of the tasks required to get ready to roll out. This chapter covers how to document and version the RESTful web API of your Restlet application.

First we discuss the use cases, pitfalls, and recommendations when documenting and versioning your web API. Documenting is essential in helping a development team communicate during active development or maintenance and helping users learn how to use it. Versioning ensures that existing clients won’t break and alienate your user community.

We cover the Web Application Description Language (WADL) that’s well-suited for documentation of RESTful web APIs and the Restlet extension for WADL, including WadlApplication, WadlServerResource, and other artifacts. You learn how to progressively describe parts of a WADL document, such as the application title and description, the list of resources, their names, URI paths, methods, and representations. To illustrate the use of this extension you’ll reuse the sample RESTful mail application developed in previous chapters.

Finally you’ll see how easy it is to automatically convert the WADL documents into a user-friendly HTML document.

6.1. The purpose of documentation and versioning

6.2. Introducing WADL

6.3. The WadlApplication class

6.4. The WadlServerResource class

6.5. Automatic conversion to HTML

6.6. Summary