http-snap

Save a snapshot of an HTTP API's response structure, then check if the structure ever changes.

Ignores value changes — only flags when keys are added, removed, or change type. Snapshots are stored as plain JSON files you can commit to git, so your whole team gets alerted when an upstream API breaks.

---

Why?

Existing tools compare two live endpoints simultaneously (like api-diff) or require a cloud account.
http-snap is different:

• Save once → check anytime later
• Structural-only diff: ignores value changes, only catches schema breakage
• Git-friendly: snapshots live in .http-snaps/ → commit them
• CI-ready: --strict exits 1 on any structural change
• Zero dependencies: pure Node.js built-ins

---

Install

npm install -g http-snap

Or run without installing:

npx http-snap save my-api https://api.example.com/endpoint

---

Usage

# Save a snapshot
http-snap save <name> <url>

# Check for structural changes
http-snap check <name> <url>

# List all saved snapshots
http-snap list

# Show a saved snapshot's structure
http-snap show <name>

---

Examples

# Save the shape of a GitHub user response
http-snap save github-user https://api.github.com/users/octocat

# Check it a week later
http-snap check github-user https://api.github.com/users/octocat

# Compare staging vs saved production snapshot
http-snap check prod-users https://staging.myapp.com/api/users/1

# With auth header
http-snap save orders https://api.myapp.com/orders/1 --header "Authorization: Bearer $TOKEN"

# CI mode — fail the pipeline if structure changed
http-snap check prod-users https://api.myapp.com/users/1 --strict

---

Example Output

No changes:

http-snap — Structural diff for "github-user"
  Snapshot: https://api.github.com/users/octocat  (saved 2026-05-20T10:00:00Z)
  Current:  https://api.github.com/users/octocat

✓ No structural changes detected.

Changes detected:

http-snap — Structural diff for "prod-users"

⚠  3 structural change(s) found:

  + .data.subscription          → {"plan":"string","expiresAt":"string"}
  - .data.legacyPlan            was "string"
  ~ .data.role                  string → number

---

CI Integration

# .github/workflows/api-monitor.yml
name: API Snapshot Check
on:
  schedule:
    - cron: '0 9 * * 1-5'   # every weekday morning
  push:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx http-snap check prod-api https://api.myapp.com/health --strict

Commit your .http-snaps/ folder. When the API changes, the CI job fails.

---

How It Works

1. Fetch the URL and parse the JSON response
2. Extract shape: recursively walk the JSON, replacing all values with their type ("string", "number", "boolean", "null", or nested shape)
3. Save/compare the shape as JSON in .http-snaps/<name>.json
4. Diff: find keys added, removed, or changed type — ignore value changes

Array items: the shape of the first element is used as representative.
Nesting depth is capped at 8 levels to keep snapshots readable.

---

Snapshots Directory

Snapshots are stored in .http-snaps/ relative to where you run the command.

.http-snaps/
  github-user.json
  prod-api.json
  staging-orders.json

Each file looks like:

{
  "name": "github-user",
  "url": "https://api.github.com/users/octocat",
  "status": 200,
  "savedAt": "2026-05-20T10:00:00.000Z",
  "shape": {
    "login": "string",
    "id": "number",
    "avatar_url": "string",
    "public_repos": "number"
  }
}

---

License

MIT

---

Keywords

api snapshot · response schema · contract testing · api structure diff · schema snapshot · api regression · json shape · api monitoring · zero dependencies · cli

---

Built to solve, shared to help — Rushabh Shah 🛠️✨

_{One of 40+ zero-dependency developer CLI tools — no node_modules, ever.}