Using Dredd, API Blueprint, and Drakov to Document, Test, and Mock APIs

When developing applications, frontend developers tend to be design‑driven while backend developers focus on data, which often creates integration gaps between the expectations of each team.

Introduction

In this article we present a technology stack that bridges the gap between frontend and backend developers by allowing us to document APIs and continuously test them after implementation.

The stack includes:

Dredd – an API testing tool that works with API Blueprint and Swagger description formats.

API Blueprint – a specification language with a Markdown‑like syntax for documenting APIs.

Drakov – a tool that can host a mock server based on an API Blueprint file.

The examples use a simple Node.js API built with Express middleware.

Installation and Setup

Dredd runs on Node.js, so ensure Node.js and npm are installed. Install Dredd globally with: npm install -g dredd Verify the installation:

dredd --version

Simple API Blueprint Example

Assume we have an endpoint to create a new user: POST /api/users The request body is JSON containing an email and password:

{
  "email": "[email protected]",
  "password": "pa55w0rd"
}

The corresponding API Blueprint specification is:

FORMAT: 1A
# Dredd example
## Users [/api/users]
### Create User [POST]
+ Request (application/json)
{
  "email": "[email protected]",
  "password": "pa55w0rd"
}
+ Response 200 (application/json; charset=utf-8)
  + Headers
    jwt-token: (string, required)
  + Body
  {
    "id": 1,
    "email": "[email protected]",
    "password": "pa55w0rd",
    "provider": "local",
    "role": "user"
  }

We can validate the implementation against the Blueprint file in two ways.

Manual Run

Run Dredd by specifying the Blueprint file and the API URL: dredd api-description.apib http://localhost:9090 This command assumes the Blueprint file is named api-description.apib and the API is running locally on port 9090.

Configured Run

A simpler setup is to run dredd init, which launches a wizard to create a dredd.yml configuration file. After answering the prompts, execute tests with: dredd Typical output looks like:

info: Configuration './dredd.yml' found, ignoring other arguments.
warn:
Apiary API Key or API Project Subdomain were not provided.
info: Starting backend server process with command: npm run start
info: Waiting 3 seconds for backend server process to start
> [email protected] start /Users/code/dredd-example
> node server/app.js
Express server listening on 9000, in development mode
info: Beginning Dredd testing...
pass: POST (200) /api/users duration: 55ms
complete: 1 passing, 0 failing, 0 errors, 0 skipped, 1 total
complete: Tests took 901ms
POST /api/users 200 4.167 ms - 151
complete: See results in Apiary at: https://app.apiary.io/public/tests/run/…
info: Backend server process exited

Since no Apiary key was provided, the test run is saved as a public run for 24 hours.

Setup and Teardown Hooks

Dredd supports hooks for setup, teardown, custom expectations, authorization handling, and data sharing. Hooks can be written in any supported language; here we use Node.js.

Create a hook file (e.g., dredd-hooks.js) in the project root.

Two ways to tell Dredd about the hook file:

Pass the file path via the --hookfiles argument: dredd --hookfiles=dredd-hooks.js Or add hookfiles: dredd-hooks.js to dredd.yml.

Example hook file that creates a test user before a "Delete User" transaction and cleans it up afterward:

var hooks = require('hooks');
var User = require('../dredd-example/server/api/user/user.service');
var testStash = { newUserId: null };

hooks.before('Users > Delete User', function(transaction) {
  hooks.log('Executing hook "before" transaction "Users > Delete User"');
  User.save({ email: '[email protected]', password: '12345' }, function(err, newUser) {
    if (!err) {
      hooks.log('New user created');
      testStash.newUserId = newUser.id;
    } else {
      transaction.fail = 'Unable to create new user';
    }
  });
});

hooks.after('Users > Delete User', function(transaction) {
  hooks.log('Executing hook "after" transaction "Users > Delete User"');
  if (testStash.newUserId != null) {
    User.delete(testStash.newUserId);
  }
});

The hook declares a testStash object to store the newly created user ID, fails the test if creation fails, and deletes the user after the test.

Mock Server Setup

When an API is documented in API Blueprint format, the same file can be used to launch a mock server for frontend developers. The tool for this is Drakov.

Install Drakov globally: npm install -g drakov Run Drakov pointing at the Blueprint file: drakov -f api-description.apib Typical output:

[INFO] No configuration files found
[INFO] Loading configuration from CLI
DRAKOV STARTED
[LOG] Setup Route: GET / Get Message
[LOG] Setup Route: POST /api/users Create User
[LOG] Setup Route: GET /api/users/:id Get User Info
[LOG] Setup Route: DELETE /api/users/:id Delete User
Drakov 1.0.4 Listening on port 3000

Now any HTTP request can be made against the mock API and the responses defined in the documentation will be returned.

Final Thoughts

The tools presented—Dredd, API Blueprint, and Drakov—are simple yet powerful, covering API documentation, automated testing, and mock server provisioning. Dredd offers many options and integrates with major CI systems, providing a safety net for developers. API Blueprint is a highly expressive format for describing request and response details, while Drakov can be started with a single command to mock APIs instantly.

All of this can be set up in a few hours, after which you can say goodbye to undocumented APIs.