Initial commit: API Snapshot CLI - Record HTTP traffic and generate mock servers

2026-02-04 13:33:41 +00:00
parent 1e613fc364
commit 825f34c16e
1 changed files with 222 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,223 @@
-# api-snapshot-cli
+# API Snapshot CLI

-A CLI tool that records HTTP API traffic and generates local mock servers from recorded responses
+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