How To Design Your Next REST API?

This blog post is focused on how to design a REST API implementation with:

• good productivity,
• great performance,
• a decent auto-generated/always up-to-date documentation for REST API users/developers, including REST API libraries for many of the popular languages.

I’ll explain here what I used to do ‘til last week and some few projects I’ve discovered recently which have helped me a lot in order to achieve the above goals.

Context

I am working on a REST API for an under the radar project started a few months ago. This project is still in early phases and plenty of development is left to be done.

The idea for this REST API was to give it a first-class citizen status, meaning that the webapp front-end would actually go through this REST API instead of calling directly a service layer. This choice enforces some qualities for the REST API: it has to be clean and consistent (otherwise you’ll be pissed off when working on the webapp front-end), and it also means that integrations tests on the webapp front-end will also ensure that the REST API implementation is working (depending on how good your webapp tests are, of course!).

REST API implementation

Initially a few technically choices were made in order to build a REST API, especially:

• Netty for its async support of HTTP requests (actually using 3.2.x versions and not the non-released Netty 4.x ones),
• JAXB for the Object/XML mappings,
• Jackson for the Object/Json mappings,
• custom Netty handlers scanning for Spring-MVC annotations in order to expose a REST API.

As I was searching for a way to use WebSockets between this Netty application and the webapp front-end, I noticed that support for WebSockets was recently improved in Netty.

While reading this blog post/announcement, I noticed at the end of the post that they used code from a project called Webbit. Overwall I wasn’t intestered much in Webbit and thought instead that I should upgrade to Netty 4 in order to benefit from a better WebSockets implementation. Scanning through Webbit Wiki, I found another side project called Webbit-REST.

This project is a really nice little gem as it allows to expose JAX-RS resources via Netty (it’s based on Resteasy underneath).

So this brings the performance of Netty with the productivity of JAX-RS.

Documentation & REST API Client Libraries

Being able to produce a great REST API implementation is obviously a good step, but I was still lacking a good REST API documentation. I was searching for a solution which would be based on my code instead of some documentation I would have to maintain manually.

I remembered that a long time ago, I used some WADL based documentation generators, but frankly the generated documentation wasn’t that great… Moreover WADL support in Resteasy being not that great, this option was opted out really fast.

So I came back to searches on Google in order to figure out what solution other REST API designers/implementors used…

And finally, I discovered Enunciate. This tool can easily be plugged in any Maven build and can generate documentation of REST resources based on JAXB and Jackson annotations but also extract Javadoc comments in order to build a decent documentation. I actually invite you to have a look at a sample REST API documentation available on the project website.

Moreover it is not limited to generating documentation. It can also generate REST API clients in C, Objective-C, Java, .Net, etc.

I guess, it’s now time for me to go back to my REST API implementation :-)