WavebreakmediaMicro - Fotolia

Get started Bring yourself up to speed with our introductory content.

Using API Blueprint and Dredd for stronger, test-driven documentation

While the benefits of test-driven development are still debated, there are plenty of arguments in its favor. Learn more about TDD, including a particularly helpful markup language.

Test-driven development (TDD) is defined as a software development practice that relies on the repetition of a very short development cycle. Requirements are turned into specific test cases, then the software is improved to pass new tests only.

If you are new to the concept of TDD, then that explanation might not be entirely clear. The basic idea is that unit tests are written before the software itself. This allows developers to ensure that any code written adheres strictly to the acceptance criteria put forth at the beginning of the project. The pros and cons of traditional TDD can be argued until the very end, but the one thing that we can all agree is, TDD ensures that your code does exactly what it is intended to do.

Why TDD?

Although benefits of TTD are often debated, especially in regards to architecture, the practice itself is a perfect fit for API design. While it can sometimes feel overwhelming to build an entire test suite before putting a pen on a paper (or code onto a screen, as it were), the concept of TDD can be applied directly to API design through an obvious medium: documentation.

In an ideal world, API documentation is a perfect representation of the API itself.

In an ideal world, API documentation is a perfect representation of the API itself. Examples are unambiguous, structure intuitive and it never runs out of date. Well, we all know that this is not an ideal world. While documentation is, in my humble opinion, the most important part of an API, it is also one of the most frequently ignored. We've all run into incomplete or incorrect documentation in past, and while it can be frustrating, to say the least, it can also damage productivity. If we have to take time to reverse-engineer a third-party API, we might as well build an interface in-house.

By applying the practice of test-driven development to your API through its documentation, you can provide accurate documentation to your users by using it to verify its own accuracy. This type of checks-and-balances system saves both you and your users a lot of time.

API Blueprint and Dredd

So, you probably must be thinking, how do we actually accomplish this? How do we use our API documentation as a living and breathing test suite? The answer to these questions lies in a markup language designed specifically for API documentation. API Blueprint is a markdown-like language that encourages better API design through abstraction. Rather than simply writing documentation, API Blueprint actually allows you to create documentation using the same methodical approach you would in your unit tests.

Here's a quick example of that abstraction from the API Blueprint website:

# Data Structures
## Blog Post (object)
+ id: 42 (number, required)
+ text: Hello World (string)
+ author (Author): - Author of the blog post
## Author (object)
+ name: Boba Fett
+ email: [email protected]
# Blog Posts [/posts]
## Retrieve All Posts [GET]
+ Response 200 (application/json)
    + Attributes (array[Blog Post])

Okay, let's break this down a little bit. While it is obviously very organized and readable, there are some nuances that might not be immediately clear. The first thing worth noting is that data structures have been broken out and defined in separate sections. What this does is enable modularity in the documentation, which allows us to reference pre-defined objects in our API endpoints. The /posts endpoint is a perfect example for this behavior. Instead of repeating the Blog Post object in the response object, we can simply reference the definition and have it automatically parsed.

API Blueprint is only half of the solution. After we've designed, documented and built our API, we still have to set up our documentation test suite. As API Blueprint gives us a structured, parsable document, there are third-party tools that can make this surprisingly easy. API Blueprint's weapon for validating documentation is Dredd, "a language-agnostic command-line tool for validating [an] API description document against [back-end] implementation of the API."

Dredd is a fantastic open source tool that can parse your API Blueprint documentation and verify its accuracy against a test server. Verification is accomplished by creating expectations based on requests and responses described in the API Blueprint document; making requests to an API test server; and then checking if the responses match the documented responses.

The true beauty of Dredd is not that it can be used to validate your documentation, but that it is supported by any *nix-based continuous integration platform. That means that every time you push new code to your API (or changes to the documentation), your chosen CI platform can automatically validate them against each other without any additional overhead on your development workflow.

While tools like Dredd are often described as a way to validate the implementation of your API, I prefer to think of it as a way to validate the accuracy of your documentation. Accurate and reliable documentation is the most important part of any API and by using tools like API Blueprint and Dredd, you can ensure that your API documentation and implementation are always in sync.

Next Steps

Why continuous DevOps documentation is necessary

How to establish a strong RESTful API testing program

Handbook: Creating a clearly defined API management strategy

Dig Deeper on API management