Apiary

Go to Navigation
Back to Articles

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.

  • 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

      npm install -g dredd
    
  • 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 ( Build Status ) 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