Joeri Smits

Developer, aerial photographer and tech enthousiast. Looking into technology of tomorrow. Located in Nijmegen, NL

Create testable API documentation with Dredd

18 May 2018

Bow and arrow aiming on target

Recently I was involved in the design, development and testing phase of an API. One major key factor of a well-developed API is to have well-written documentation with it. Unfortunately, documentation is something traditionally developers pay little attention to. It’s much easier for a developer to write the actual code than to write good documentation. This article explains how I managed to start writing API documentation at the very beginning of the project, and how this improved the development and testing phase.

Development phases of an API

So basically each API starts with a preparation phase. During this phase I looking for the optimal tool to design and document our API. I quickly stumbled upon Apiary.io. Apiary utilizes the power of API Blueprint to quickly build you a representable API documentation that can be accessed online. We quickly started to design our API and as we did the API Blueprint file evolved. By the end of our designing phase, we got an API Blueprint file that described all the functionality of the API for our first sprint. At this phase in time Apiary got started showing it’s potential.

Testing things

At this point, we were done with the designing phase of the API. In order to start our development, we needed something very important. Yes! We needed automatic testing. Luckily API Blueprint has the ability to write down the request format and the response format for each endpoint. This can be utilized in order to test an actual API. We test if the API has all endpoints in our API Blueprint documentation and if it responds in the correct format as described in our documentation.

Dredd (No, not the movie) can actually do this for you! Dredd is an open-source Language-agnostic HTTP API Testing Framework. Which seems like a mouthful but actually has a pretty simple meaning. Dredd compares your API Blueprint with an actual online environment. Dredd tests each endpoint in your API and reports back if a test has passed or failed and more importantly why it failed. If your test fails it is likely that your API is not matching your documentation (or vice versa). Using this in a Test Driven Development way will make sure your documentation always matches your API and therefore eliminating out of date or incomplete API documentation.

Testing with Dredd can be very basic or very extensive. API Blueprint gives you all kind of possibilities to validate data. One of them is in the form of describing a JSON Schema to validate data. Dredd uses these validators in API Blueprint to check if your API actually validates.

Dredd is actually pretty simple to use and can be integrated with Apiary and Continuous integration (CI) platforms. Apiary has well-written instruction on how to integrate Dredd with Apiary.

A failed test from Dredd in Apiary.io

Conclusion

By using Dredd in combination with Apiary our documentation stayed up to date during the development of our API. Dredd is also a big time saver because our developers don’t need to check the documentation manually each time we push a change. Dredd will do this automatically for us.

One of the downsides of using API Blueprint with Apiary is that you are limited to only use one .apib file. Especially when your API gets a little bigger this can sometimes cause you to lose overview when making changes to the API Blueprint file.

If you have not yet tried Apiary and Dredd I would suggest you give it a go, and see if testing your documentation with Dredd adds value to your development cycles.

Good first start point in using Dredd with API Blueprint and Apiary