RESTful Java Web Services - Third Edition

The need for an interface contract

Having a well-documented interface contract enables design-time discovery. The API documentation for RESTful web services provides a standard, language-independent interface, which can be used by both humans and machines to discover the capabilities of APIs without accessing the source code. This chapter introduces a few of the various API documentation tools and options that you might choose from.

Let's start by discussing one of the earliest solutions for RESTful web API documentation—Web Application Description Language (WADL).