🖭 API Tape

High-integrity HTTP proxy for deterministic API record & replay.

API Tape is a zero-config CLI tool that acts as a transparent HTTP proxy. It records API responses to local JSON files ("tapes") and replays them instantly—perfect for offline development, flaky API testing, and reproducible demos.

Note

v1.6.2 Highlights: Introduced a structural Graceful Shutdown mechanism for all platforms (including Windows), a new Comprehensive Examples suite, and improved test reliability in CI environments.

Features

• Record Mode — Proxies requests to your target API and saves responses
• Replay Mode — Serves cached responses instantly from disk
• Hybrid Mode — Replays cached tapes, falls back to upstream on cache miss
• Forensic CLI — List, inspect, clear, and prune tapes with tape
• Security Redaction — Mask sensitive response headers and JSON body paths
• Non-Deterministic Matching — Handle shifting query params and unstable JSON bodies
• Runtime Metrics — Real-time and shutdown stats for hit rates and latency
• Binary Safe — Handles images, compressed payloads, and any content type
• Replay Header — Responses include X-Api-Tape: Replayed for easy debugging

---

Installation

npm install -g @laphilosophia/api-tape

Or use it directly with npx:

npx @laphilosophia/api-tape --target "https://api.example.com" --mode record

---

Quick Start

Step 1: Record API Responses

tape --target "https://jsonplaceholder.typicode.com" --mode record

In another terminal:

curl http://localhost:8080/todos/1

You'll see ● RECORD GET /todos/1 in the terminal and a new tape file in ./tapes/.

Step 2: Replay Offline

Stop the server and restart in replay mode:

tape --target "https://jsonplaceholder.typicode.com" --mode replay

curl http://localhost:8080/todos/1

You'll see ↺ REPLAY_HIT GET /todos/1 — the response comes from disk, no network needed!

Step 3: Hybrid Mode (Replay + Fallback)

Run in hybrid mode to replay from disk and fallback to upstream when a tape is missing:

tape --target "https://jsonplaceholder.typicode.com" --mode hybrid --record-on-miss true

• If a tape exists → replayed instantly.
• If tape is missing → upstream request is proxied.
• With --record-on-miss true, miss responses are automatically saved as new tapes.

---

CLI Options

Serve command

Both legacy mode (tape --target ...) and explicit serve command (tape serve --target ...) are supported.

Option	Description	Default
-t, --target <url>	Target API URL (required)	—
-m, --mode <mode>	Operation mode: record, replay, or hybrid	replay
-p, --port <number>	Local server port	8080
-d, --dir <path>	Directory to save tapes	./tapes
--record-on-miss <boolean>	In hybrid mode, save upstream response when tape is missing	true
--redact-header <headers>	Comma-separated response header names to redact	—
--redact-json-path <paths>	Comma-separated JSON paths to redact in response bodies	—
--stats-interval <seconds>	Emit runtime metrics every N seconds (0 disables)	0
--stats-json	Emit metrics as JSON lines	false
--match-strategy <strategy>	Tape matching strategy: exact, normalized, or body-aware	exact

Runtime stats

tape serve --target "https://jsonplaceholder.typicode.com" --mode hybrid --stats-interval 10

For machine-readable output:

tape serve --target "https://jsonplaceholder.typicode.com" --stats-interval 10 --stats-json

On shutdown, API Tape flushes one immediate STATS snapshot (if interval is enabled) and always prints a final summary (FINAL_STATS).

Redaction options

tape serve --target "https://api.example.com" --mode record \
  --redact-header authorization,cookie \
  --redact-json-path user.profile.email,token

--redact-json-path applies only when response content-type is JSON.

Match Strategies

Use these strategies to handle non-deterministic API behaviors and improve replay hit rates:

• exact (default): Hashes the literal METHOD|URL. Use for simple, static APIs.
• normalized: Canonicalizes query parameters by sorting them alphabetically.
  • Transforms: /search?page=1&q=test → /search?q=test&page=1
  • Benefit: Drastically improves hit rates for clients that send query params in varying orders.
• body-aware: Combines the normalized URL with a canonicalized request body signature.
  • Handles: Differences in JSON key order or spacing in POST/PUT requests.
  • Benefit: Essential for GraphQL or complex REST APIs where the same URL is used for different operations based on the body payload.

Tape management commands

Manage your forensic substrate with built-in tape utilities:

# List all recorded tapes with their method, route, and timestamp
tape list --dir ./tapes

# Inspect a specific tape's metadata, status, and headers
tape inspect <hash> --dir ./tapes

# Clear all tapes from a directory (requires --yes confirmation)
tape clear --yes --dir ./tapes

# Prune tapes older than N days to keep your local environment clean
tape prune --older-than 30 --dir ./tapes

---

Tape Format

Each tape is a JSON file named with an MD5 hash of METHOD|URL:

{
  "schemaVersion": 1,
  "meta": {
    "url": "/todos/1",
    "method": "GET",
    "timestamp": "2026-01-14T19:12:39.000Z",
    "matchStrategy": "normalized"
  },
  "statusCode": 200,
  "headers": { ... },
  "body": "eyJ1c2VySWQiOjEsImlkIjoxLC..."
}

The body is base64-encoded for binary safety.

---

Development

npm run build
npm test

---

CI

A GitHub Actions workflow runs npm test on both Linux and Windows for pushes and pull requests.

---

---

Contributing

We welcome contributions! Please see our CONTRIBUTING.md for guidelines on how to get started. All participants are expected to follow our CODE_OF_CONDUCT.md.

Security

To report a security vulnerability, please use the process described in SECURITY.md.

Support

If you need help using API Tape, check our SUPPORT.md or join the conversation in GitHub Discussions.

---

Use Cases

• Offline Development — Work without internet or VPN
• Flaky API Testing — Eliminate network inconsistencies in tests
• Demo Environments — Reproducible API responses for presentations
• Rate Limit Bypass — Develop against recorded responses

---

License

MIT © Erdem Arslan