api-diff-cli

Compare API responses and detect changes — perfect for regression testing.

Zero dependencies. Uses Node.js built-in https module only.

Install

npm install -g api-diff-cli

Or run without installing:

npx api-diff-cli <url1> <url2>

Usage

Compare two API versions

api-diff https://api.example.com/v1/users https://api.example.com/v2/users

Output:

  api-diff-cli v1.0.0

  URL 1: https://api.example.com/v1/users → HTTP 200
  URL 2: https://api.example.com/v2/users → HTTP 200

  + users[2].role: "admin"
  - users[0].legacy_id: 42
  ~ users[1].profile.avatar:
      URL 1: null
      URL 2: "https://cdn.example.com/avatars/2.png"

  Summary: 1 added, 1 removed, 1 changed

Save a baseline snapshot

api-diff --save baseline.json https://api.example.com/users

Compare live response against baseline

api-diff --baseline baseline.json https://api.example.com/users

Ignore volatile fields

api-diff --ignore-keys "updatedAt,timestamp,requestId" \
  https://old.api/data https://new.api/data

POST request comparison

api-diff --method POST --body '{"query":"test"}' \
  https://old.api/search https://new.api/search

Custom headers (auth, etc.)

api-diff --header "Authorization:Bearer mytoken" \
  https://api.example.com/v1/profile https://api.example.com/v2/profile

CI Integration

api-diff exits with code 1 when differences are found — drop it straight into any pipeline.

GitHub Actions

name: API Regression Check

on: [push, pull_request]

jobs:
  api-diff:
    runs-on: ubuntu-latest
    steps:
      - name: Check API for regressions
        run: |
          npx api-diff-cli \
            https://staging.myapp.com/api/users \
            https://prod.myapp.com/api/users

Baseline workflow (recommended for staging deploys)

jobs:
  regression:
    steps:
      # After deploy to staging, compare against prod baseline
      - name: Save production baseline
        run: npx api-diff-cli --save prod-baseline.json https://prod.myapp.com/api/data

      - name: Deploy to staging
        run: ./deploy.sh staging

      - name: Check for regressions
        run: |
          npx api-diff-cli \
            --baseline prod-baseline.json \
            --ignore-keys "timestamp,requestId,serverTime" \
            https://staging.myapp.com/api/data

Pre-commit hook (.git/hooks/pre-push)

#!/bin/bash
echo "Checking API for regressions..."
api-diff \
  --baseline ./test/baseline.json \
  --ignore-keys "updatedAt,cachedAt" \
  https://localhost:3000/api/health || {
    echo "API regression detected! Aborting push."
    exit 1
  }

CircleCI

- run:
    name: API Regression Test
    command: |
      npx api-diff-cli \
        $OLD_API_URL/endpoint \
        $NEW_API_URL/endpoint

Options

| Flag | Description | |------|-------------| | --method <METHOD> | HTTP method (default: GET) | | --body <JSON> | Request body for POST/PUT | | --header <K:V> | Add a request header (repeatable) | | --ignore-keys <k1,k2> | Comma-separated keys to skip in diff | | --baseline <file> | Compare live URL against saved JSON baseline | | --save <file> | Save API response as baseline JSON file | | --no-color | Disable ANSI color output | | --help | Show help |

Exit Codes

| Code | Meaning | |------|---------| | 0 | No differences found (or baseline saved) | | 1 | Differences detected | | 2 | Error (network failure, invalid JSON, etc.) |

Diff Output

The diff engine does a deep recursive comparison of JSON objects and arrays:

• + green — field added in URL 2 / live response
• - red — field removed vs URL 1 / baseline
• ~ yellow — field value changed (shows both old and new)

Paths use dot notation and bracket notation:

users[0].profile.avatar: null → "https://..."
meta.pagination.total: 42 → 43
settings.features.darkMode: false → true

License

MIT © Wilson Xu