DEV Community

Cover image for How to Validate Your API Against Its Spec Without Dredd
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Validate Your API Against Its Spec Without Dredd

Dredd solves a practical API quality problem: it turns your API description into a contract test. Point Dredd at an OpenAPI document or API Blueprint file, point it at a running server, and it sends the documented requests to the live backend. If your spec says GET /orders/{id} returns 200 with id and status, Dredd checks that the implementation actually returns that shape.

Try Apidog today

That contract-testing model is valuable because API drift is expensive. A frontend team builds against the documented contract, the backend renames a field, the docs are not updated, and the bug shows up in production. Dredd catches that class of failure by making the spec executable.

The tradeoff is operational. Dredd is a Node.js CLI with its own config, a separate API description artifact, and hooks for anything beyond simple request/response checks. If you want the same CI gate without maintaining a disconnected spec file and hooks codebase, Apidog is built around an integrated workflow: API design, schemas, test scenarios, assertions, and CLI execution live in one project.

What Dredd does well

Dredd earned its place because its core workflow is simple and useful.

It validates the live implementation

Many tools validate that an OpenAPI file is syntactically valid. Dredd goes further: it sends requests to the real backend and compares the real response with the documented example.

A passing Dredd run means:

  • the service is reachable
  • the documented request can be executed
  • the response matches what the spec promised

It supports API Blueprint and OpenAPI

Dredd supports API Blueprint and OpenAPI 2/3. That matters if you have older Blueprint-based documentation or existing Swagger/OpenAPI files that you do not want to convert before testing.

It supports hooks in multiple languages

For real APIs, you usually need setup logic:

  • fetch an auth token
  • seed test data
  • skip specific transactions
  • clean up state after a test
  • modify requests before sending them

Dredd handles that through hooks. The default hook handler is Node.js, but Dredd also supports hooks in Python, Ruby, Go, PHP, Rust, and other languages.

It is open source and CI-friendly

Dredd installs and runs from the command line:

npm install -g dredd
Enter fullscreen mode Exit fullscreen mode

Because it exits with a non-zero code when validation fails, it works naturally in CI pipelines.

Dredd is a good fit when you want a self-hosted, open-source contract test runner and are comfortable maintaining the spec and hook files yourself.

Where Dredd adds maintenance work

Dredd’s model works, but it usually creates three moving parts.

1. The spec is a separate artifact

Dredd validates your implementation against a description file, usually something like:

openapi.yaml
Enter fullscreen mode Exit fullscreen mode

That file often lives separately from:

  • the API design workflow
  • the test scenarios
  • the running service
  • the implementation code

Dredd can tell you whether the implementation matches the spec. It cannot ensure the spec itself is still the source of truth unless your team keeps it updated.

2. Hooks become a second test codebase

Simple read-only endpoints may work with little configuration. Stateful APIs usually need hooks.

For example, you may need to:

beforeEach(function(transaction) {
  transaction.request.headers.Authorization = `Bearer ${process.env.API_TOKEN}`;
});
Enter fullscreen mode Exit fullscreen mode

That hook logic grows over time. Eventually, you are maintaining both:

  • the application code
  • the Dredd hook code that makes the application testable

3. Coverage depends on documented examples

Dredd tests the examples in your API description. If an endpoint has one happy-path example, that is what gets exercised.

To cover more behavior, you must add more examples or write more hook logic for cases such as:

  • invalid input
  • missing auth
  • validation errors
  • empty states
  • pagination boundaries
  • role-based access rules

The result is useful, but coverage is only as complete as the examples you maintain.

The integrated path: keep spec and tests together

Apidog takes a different approach: the API definition, schemas, test scenarios, assertions, and CLI execution all live in the same project.

Instead of maintaining a separate openapi.yaml only for Dredd, you can:

  1. Design or import the API in Apidog.
  2. Build requests and test scenarios from the same schemas.
  3. Add assertions against the defined response structure.
  4. Run those tests locally or in CI with the Apidog CLI.

Apidog supports OpenAPI 2/3, Swagger documents, and Postman collection imports. If you use a spec-first workflow, see spec-first API development. If you want to validate the OpenAPI document itself before running contract tests, see validating OpenAPI specs.

The key difference is that assertions are built against the schemas already stored in the project. When a scenario calls:

GET /orders/{id}
Enter fullscreen mode Exit fullscreen mode

the response can be checked against the schema for that endpoint, not against a copied example maintained elsewhere.

For more on this workflow, see API contract testing and bidirectional contract testing.

Install the Apidog CLI

The Apidog runner is published as apidog-cli.

Install it globally:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

The binary is:

apidog
Enter fullscreen mode Exit fullscreen mode

A basic test run looks like this:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

Where:

  • --access-token authenticates the CLI
  • -t points to a test scenario ID
  • -e selects an environment ID
  • -r cli prints readable output in the terminal

You do not need to memorize those IDs. In Apidog:

  1. Open the test scenario.
  2. Go to the CI/CD tab.
  3. Choose the command-line option.
  4. Generate an access token.
  5. Copy the generated apidog run command.

Store the token as a CI secret and reference it as an environment variable:

$APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Run multiple scenarios

To run a folder or test suite instead of one scenario, use a folder ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -f <folderId> \
  -e 1629989 \
  -r html,junit \
  --out-dir ./test-reports
Enter fullscreen mode Exit fullscreen mode

Useful reporters include:

  • cli — terminal output
  • html — self-contained report for build artifacts
  • junit — XML for CI dashboards
  • json — structured output for automation

For the full option list:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Dredd vs Apidog

Area Dredd Apidog
Core idea Validate implementation against an API description Validate implementation against the spec used by the project
Runtime Node.js with npm install -g dredd Node.js with npm install -g apidog-cli
Spec support API Blueprint, OpenAPI 2/3 OpenAPI 2/3, Swagger import, Postman import
Spec location Separate file maintained by hand Same project as tests and schemas
Setup logic Hooks file such as hooks.js Pre-request and post-request JavaScript in scenarios
Test authoring Examples in the description Scenario editor against project schemas
Coverage model As complete as the examples in the spec Schema assertions plus custom test scenarios
Reporters Built-in plus add-ons cli, html, json, junit
Hosting model Self-hosted, open source Hosted project, CLI runs anywhere

Choose Dredd if you need a fully local, open-source, no-account CLI and your team is fine maintaining hooks and spec files.

Choose the integrated workflow if you want to reduce artifact drift and keep design, tests, schemas, and contract validation in one place.

Wire Apidog into GitHub Actions

The Apidog CLI exits:

  • 0 when tests pass
  • non-zero when tests fail

That makes it suitable for CI gates.

A minimal GitHub Actions workflow:

name: api-contract-check

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g apidog-cli

      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

That is enough to fail the build when the live API no longer matches the expected contract.

A Dredd pipeline is structurally similar: install the CLI and run one command. The difference is that Dredd also needs the external spec file and any hook files to stay current.

If your larger problem is tool drift between Swagger, Postman, and tests, see OpenAPI-driven testing against Swagger and Postman drift. If you are comparing Java-based workflows, see Rest Assured API testing and Rest Assured alternatives. You can also run Apidog from your editor with the VS Code extension.

FAQ

Is Apidog a drop-in replacement for Dredd?

No. Apidog does not convert dredd.yml and hooks.js into Apidog scenarios.

The migration path is:

  1. Import your OpenAPI spec.
  2. Recreate the important validation flows as Apidog scenarios.
  3. Add schema assertions and custom checks.
  4. Run them with apidog run.

If your Dredd suite is large and stable, migration is a real project. The benefit is reducing ongoing maintenance of separate spec and hook artifacts.

Does Apidog validate the live implementation like Dredd?

Yes. The CLI sends real requests to your running service and validates actual responses against the schemas in your Apidog project.

How do I handle auth and setup logic?

Use pre-request and post-request scripts in JavaScript.

Common use cases include:

  • fetching access tokens
  • setting dynamic headers
  • seeding test data
  • transforming payloads
  • writing custom assertions
  • cleaning up after requests

The setup logic lives with the scenario instead of in a separate hooks file.

What does Dredd do that Apidog does not?

Dredd has two important advantages for some teams:

  • it is fully self-hosted and open source
  • it supports API Blueprint natively

If your workflow requires a no-account local tool or depends heavily on API Blueprint, keep that in mind before switching.

What formats can Apidog import?

Apidog supports:

  • OpenAPI 2
  • OpenAPI 3
  • Swagger documents
  • Postman collections

For background on the formats, see Swagger versus OpenAPI and the OpenAPI specification overview.

Bottom line

Dredd gets the main idea right: your API description should be tested against the running service, not treated as static documentation.

Use Dredd if you want a self-hosted open-source CLI and are comfortable maintaining a separate spec file and hook code.

Use Apidog if you want the spec, schemas, test scenarios, assertions, and CI runner in one workflow. Install the CLI, run apidog run, and gate your build on the same contract your API was designed from.

Download Apidog and import your existing OpenAPI file to run the spec-versus-implementation check from a single command.

Top comments (0)