diff --git a/README.md b/README.md index d9e5f0a..b8ef723 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,26 @@ # 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. +A CLI tool that records HTTP API traffic and generates local mock servers from recorded responses. ## 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 +- Record HTTP API traffic automatically +- Generate mock server configurations +- Replay recorded API responses +- Support for multiple HTTP methods ## 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: +## Usage ```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 +api-snapshot --help ``` ## License -MIT License +MIT