Contract Driven REST API Design

Introduction

Apidoc.js is a great inline documentation tool for RESTful web APIs.
It goes really well with Spring REST applications, you just define your API documentation as inline comments in your classes and execute the apidoc command to parse the source files and generate a static HTML documentation out of them.

placeholder

With this lightweight technology it is easy to follow a contract driven REST API design that I found really useful in my past project.
The process we followed was to design the API for the resource, document the API using the Apidoc annotations and generate a HTML documentation out of it.
The generated documentation was then published to a server and before starting the implementation we reviewed it together with fellow team members and other possible customers of the future API.
The implementation could only begin when the API was reviewed, adjusted and accepted.

placeholder

Installation

To install Apidoc you need npm package manager to be installed first.
Assume you are using mac with brew it goes as easy as:

brew install npm

After the successful installation the npm command should work in the terminal giving you the “usage…” page.
Npm installation guide can be found here: node & npm

###Configure Apidoc

Apidoc needs to be configured by creating an apidoc.json file in your project root directory.

{
"name": "Book Invetory REST API",
"version": "1.0.0",
"description": "Rest API for book-inventory-boot app",
"title": "Book Inventory Rest API",
"url" : "http://www.talangsoft.org/book-inventory-boot"
}

Configure Maven

To generate the documentation you need to configure maven to execute the apidoc command. The minimum configuration for apidoc command execution requires configuring the input and output folders.

     <plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<phase>site</phase>
<goals>
<goal>exec</goal>
</goals>
</execution>
</executions>
<configuration>
<executable>apidoc</executable>
<arguments>
<argument>-i</argument>
<argument>${project.basedir}/src/main/java/</argument>
<argument>-o</argument>
<argument>${project.build.directory}/apidocs/</argument>
</arguments>
</configuration>
</plugin>
</plugin>

You also need maven reports plugin to generate reports as part of the site phase.

    <reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>${maven.reports.plugin.version}</version>
<reportSets>
<reportSet>
<reports>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>

At this point the mvn clean site should trigger Apidoc execution, however it will not generate output by default without having Apidoc documentation embedded in your code.

Document API with Apidoc

You can now start documenting your api with using the available params.

public interface BookResource {

/**
* @api {get} /api/books/{isbn} Get book by isbn code
* @apiName getByIsbn
* @apiGroup BookResource
* @apiDescription Get a book by isbn
* @apiVersion 1.0.0
*
* @apiParam {String} isbn The isbn that identifies the book
*
* @apiSuccess {BookDTO} book The book for the isbn
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "isbn":"isbn1236",
* "title":"To Kill a Mockingbird",
* "author":"Harper lee"
* }
*
* @apiError (404) BookNotFound The book was not found
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not found
* {"errorCode":"BOOK_NOT_FOUND",
* "errorMessage":"The book was not found.",
* "params":{
* "isbn":"not-existing-isbn"
* }
* }
*
*/

BookDTO getByIsbn(String isbn);

/*...*/
}

See a complete class configuration working in the book-inventory-boot project: BookResource.java.

The Generated Documentation

The generated configuration will be in the target/apidoc directory as configured in the pom.xml. It looks like this:

placeholder See the full documentation: Book Inventory API

Summary

Documentation is one of the key factor of determining how usable your API will be. Without it even the best designed API will cause headache to the users need to rely on it.
Furthermore generating the documentation before implementation, agree in the contract upfront, minimises the changes you need to make in your code.

See the complete example in book-inventory-boot repository.