api-snapshot-cli/README.md

# 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

```bash
pip install api-snapshot-cli
```

Or from source:

```bash
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:

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

Record multiple requests from a config file:

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

### 2. Start the Mock Server

Start the mock server with your recorded snapshot:

```bash
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

```bash
curl http://127.0.0.1:8080/users
```

## Commands

### record

Record a single HTTP request and save as a snapshot.

```bash
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.

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

Example config file:
```json
[
  {"method": "GET", "url": "/users"},
  {"method": "POST", "url": "/users", "body": {"name": "test"}}
]
```

### serve

Start a mock server from a snapshot.

```bash
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.

```bash
api-snapshot list
```

### info

Show detailed information about a snapshot.

```bash
api-snapshot info <snapshot-name>
```

### delete

Delete a snapshot.

```bash
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:

```json
{
  "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

```bash
# 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

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

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

### Interactive Recording

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

## License

MIT License