API Snapshot CLI

A CLI tool that records HTTP API traffic and generates local mock servers from recorded responses. Developers can record real API calls, save them as JSON snapshots, and instantly spin up a lightweight mock server for testing - eliminating external API dependencies and rate limits.

Features

• Record HTTP Traffic: Capture HTTP requests and responses from any API endpoint
• Generate JSON Snapshots: Save recorded traffic as structured JSON files with metadata
• Mock Server: Spin up a local HTTP server that replays recorded responses
• Multi-Endpoint Support: Manage and serve multiple API endpoints from a single snapshot
• Latency Simulation: Replay responses with configurable delay for realistic testing
• Interactive Recording: Live feedback during recording with progress indicators

Installation

pip install api-snapshot-cli

Or from source:

git clone https://github.com/yourusername/api-snapshot-cli.git
cd api-snapshot-cli
pip install -e .

Quick Start

1. Record an API Request

Record a single API request:

api-snapshot record https://api.example.com/users --name my-api

Record multiple requests from a config file:

api-snapshot record-multi config.json --name my-api

2. Start the Mock Server

Start the mock server with your recorded snapshot:

api-snapshot serve my-api

The server will start on http://127.0.0.1:8080 by default.

3. Make Requests to the Mock Server

curl http://127.0.0.1:8080/users

Commands

record

Record a single HTTP request and save as a snapshot.

api-snapshot record <url> --name <snapshot-name> [options]

Options:

• --name, -n: Name for the snapshot (required)
• --method, -m: HTTP method (default: GET)
• --headers, -H: Request headers (comma-separated key:value pairs)
• --body, -d: Request body (string or @file:path)
• --description, -D: Snapshot description
• --tag: Tags for the snapshot (can be used multiple times)
• --interactive, -i: Interactive recording mode
• --count, -c: Number of requests to make
• --delay: Delay between requests in seconds

record-multi

Record multiple requests from a JSON config file.

api-snapshot record-multi <config-file> --name <snapshot-name> [options]

Example config file:

[
  {"method": "GET", "url": "/users"},
  {"method": "POST", "url": "/users", "body": {"name": "test"}}
]

serve

Start a mock server from a snapshot.

api-snapshot serve <snapshot-name> [options]

Options:

• --host, -H: Host to bind to (default: 127.0.0.1)
• --port, -p: Port to listen on (default: 8080)
• --latency, -l: Latency mode (original, fixed, random, none)
• --latency-ms: Fixed latency in milliseconds
• --latency-min: Minimum latency for random mode (ms)
• --latency-max: Maximum latency for random mode (ms)

list

List all available snapshots.

api-snapshot list

info

Show detailed information about a snapshot.

api-snapshot info <snapshot-name>

delete

Delete a snapshot.

api-snapshot delete <snapshot-name> [--force]

Configuration

Environment Variables

• API_SNAPSHOT_DIR: Default directory for storing snapshots (default: ./snapshots)
• API_SNAPSHOT_HOST: Default host for mock server (default: 127.0.0.1)
• API_SNAPSHOT_PORT: Default port for mock server (default: 8080)

Snapshot Format

Snapshots are stored as JSON files with the following structure:

{
  "metadata": {
    "version": "1.0",
    "timestamp": "2024-01-01T00:00:00",
    "description": "API snapshot description",
    "source_url": "https://api.example.com",
    "tags": ["tag1", "tag2"],
    "latency_mode": "original",
    "custom_latency_ms": null
  },
  "requests": [
    {
      "request": {
        "method": "GET",
        "url": "https://api.example.com/users",
        "headers": {
          "Accept": "application/json"
        },
        "body": null,
        "timestamp": "2024-01-01T00:00:00"
      },
      "response": {
        "status_code": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "body": "[{\"id\": 1, \"name\": \"John\"}]",
        "latency_ms": 150
      }
    }
  ]
}

Examples

Recording with Custom Latency

# Record and add latency simulation
api-snapshot record https://api.example.com/data --name my-api
api-snapshot serve my-api --latency fixed --latency-ms 100

Multi-Endpoint Snapshot

// requests.json
[
  {"method": "GET", "url": "/users"},
  {"method": "GET", "url": "/users/1"},
  {"method": "POST", "url": "/users"},
  {"method": "DELETE", "url": "/users/1"}
]

api-snapshot record-multi requests.json --name users-api
api-snapshot serve users-api

Interactive Recording

api-snapshot record https://api.example.com/users \
  --name my-api \
  --interactive \
  --count 5 \
  --delay 1.0

License

MIT License