From 825f34c16e95cb14ad7e4b61dcf5a868655775cd Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Wed, 4 Feb 2026 13:33:41 +0000 Subject: [PATCH] Initial commit: API Snapshot CLI - Record HTTP traffic and generate mock servers --- README.md | 224 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 222 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6fdf1b2..d9e5f0a 100644 --- 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 \ No newline at end of file +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 --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 --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 [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 +``` + +### delete + +Delete a snapshot. + +```bash +api-snapshot delete [--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