How To Test REST API with API Blueprint and Dredd

By netmilk (ntmlk, adam@apiary.io) on 17 Oct 2013

As a follow up for my previous blogpost which is introducing Dredd—the tool for testing APIs from API Blueprint, I’ve prepared a simple example application in Express.js to demonstrate how to write a blueprint, a backend, test it and let it be tested forever in the CI.

Note I’m using Express.js for the backend but Dredd, API Blueprint and Apiary do not depend on any specific programming language. Dredd interacts with the backend app only through the HTTP layer. That means the process as described below can be applied on any backend platform and framework in any language.

Let’s move on – it’s super-easy!

1. Write a blueprint

Start thinking about your API, create an Apiary project with a sample blueprint and save it. You can use my example blueprint. Do not forget to invite others to join the discussion. Enjoy generated documentation and play with the mock.

2. Link with GitHub

Create the GitHub project
Connect Apiary with GitHub on the setting tab
Clone the repo locally

3. Prepare the Backend Application

Swich to your local repo directory
Install Node.js

Bootstrap application environment

  npm install express coffee-script mongous

Create empty Express application in file app.coffee

  express = require 'express'
  app = express()
  app.listen 3000
  console.log('Listening on port 3000');

4. Make it Red

Add a test script to scripts/test

  #!/bin/sh
  ./node_modules/coffee-script/bin/coffee app.coffee &
  sleep 5
  PID=$!
  dredd apiary.apib http://localhost:3000/
  RESULT=$?
  kill -9 $PID
  exit $RESULT

Install Dredd globally
See the test fail
```
  $ ./scripts/test
  $ echo $?
  1
```

5. Make it Green

Write the code of the backend application
Run the test again and see it pass
```
  $ ./scripts/test
  $ echo $?
  0
```

6. Make it Eternal

And finally – the holy grail! When you plug it into a Continuous Integration system any change of the API Blueprint in your GitHub repository will update the API documentation generated by Apiary and run the test harness. At this point you have always up-to-date API documentation. And what is even better – it is absolutely free of charge!

Sign in to Travis-CI Continuous integration service
Find your project in the list of your GitHub repositories and enable it

Add a Travis dotfile to .travis.yml with:

  language: node_js
  node_js:
  - 0.8
  - 0.10
  before_install:
  - npm install -g dredd
  script: ./scripts/test
  services:
  - mongodb
  before_script:
  - mongo mydb_test --eval 'db.addUser("test", "test");'

Commit and push your work to GitHub
Wait for the build and proudly place the status badge ( ) to the Readme of your project and to the API documentation

We strongly appreciate any feedback in Dredd’s GitHub issues or directly through our support.

Supported Continuous Integration Services

Dredd works with several Continuous Integration Services. I’ve tested it with Travis-CI, Circle-CI, Codeship, Semaphore, Teamcity, Jenkins, Atlassian Bamboo and probably many others.

Travis-CI Circle-CI Codeship Semaphore Team city Jenkins Atlassian Bamboo