Literate API Testing with Dredd

I've just started my latest project at MIT, and I'm quite excited about a new piece of technology that the team uses: apiary.io.

With Apiary, we generate a simple blueprint file (source, output) which is a full description of your API. This shows off requests and responses with a bit of prose. It's all in markdown file and is very simple to get started. There is a tool called Protagonist which will parse this into a big JSON blob.

One consumer of this giant JSON blob is a tool called Dredd, which has bindings for multiple languages (including Python). This will issue the request in your apiary file to the endpoint described, and validate the the result is similar in structure to the one you described in your documentation. There are also facilities for setting up fixture data before each of the things run. You can see an example of those here.

The result of this bit of work, is you have a tool that can run on your continuous integration server which validates that your API documentation maps up to the actual implementation. Neat!

As a teaser for what I hope is to come, there's no real reason that you shouldn't also be able to build full API clients based on the output from Protagonist. The lead developer indicated they're working on something here. Stay tuned!