api-throttle-tester

A production-ready CLI tool for stress-testing API endpoints to understand rate limits, throttling behavior, and latency characteristics under load.

Features

• 🚀 Concurrent Load Testing: Test API endpoints with configurable concurrency levels
• 📊 Comprehensive Metrics: Track success rates, throttling, errors, and latency distributions
• 🎯 Rate Limit Detection: Automatically identify and report HTTP 429 (or custom) throttling responses
• 📈 Detailed Reporting: Human-readable tables or JSON output for CI/CD integration
• ⚙️ Configurable: Support for config files, custom headers, request bodies, and more
• 🧪 Well-Tested: Comprehensive test suite with unit and integration tests

Installation

Global Installation (Recommended)

npm install -g api-throttle-tester

After installation, use it from anywhere:

api-throttle-tester https://api.example.com/endpoint

Use Without Installation

npx api-throttle-tester <url> [options]

Quick Start

1. Install the tool

npm install -g api-throttle-tester

2. Run your first test

# Test a public API (safe example)
api-throttle-tester https://jsonplaceholder.typicode.com/posts/1 -t 10 -c 2

You'll see output like:

============================================================
API Throttle Test Results
============================================================

Summary:
  Successful (2xx): 10
  Throttled: 0
  Errors: 0
  Network Errors: 0

Latency:
  Average: 245.30ms
  Min: 120.00ms
  Max: 450.00ms
...

3. Test your own API

api-throttle-tester https://api.yourcompany.com/endpoint \
  -H "Authorization: Bearer your-token" \
  -t 100 -c 10

4. Get JSON output for automation

api-throttle-tester https://api.example.com/endpoint \
  --json \
  --report-file results.json \
  -t 200 -c 20

Common Use Cases

Basic Example

Test an API endpoint with default settings (100 requests, 10 concurrent workers):

api-throttle-tester https://api.example.com/endpoint

With Authentication

api-throttle-tester https://api.example.com/endpoint \
  -H "Authorization: Bearer your-token-here" \
  -H "X-API-Key: your-api-key"

POST Request with Body

api-throttle-tester https://api.example.com/users \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token" \
  -b '{"name":"John Doe","email":"[email protected]"}'

Custom Concurrency and Total Requests

api-throttle-tester https://api.example.com/endpoint \
  -t 1000 \
  -c 50 \
  -d 100

This sends 1000 total requests with 50 concurrent workers and a 100ms delay between requests per worker.

JSON Output and Report File

api-throttle-tester https://api.example.com/endpoint \
  --json \
  --report-file report.json

Custom Throttle Status Code

Some APIs use different status codes for throttling (e.g., 503):

api-throttle-tester https://api.example.com/endpoint \
  --status-as-throttle 503

Command-Line Options

Required

• <url> - API endpoint URL to test (can also be provided via --config)

Optional

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --method | -X | HTTP method (GET, POST, PUT, DELETE, etc.) | GET | | --total | -t | Total number of requests to send | 100 | | --concurrency | -c | Number of concurrent workers | 10 | | --delay | -d | Delay between requests per worker (ms) | 0 | | --header | -H | HTTP header (can be used multiple times) | - | | --body | -b | Request body (JSON string for POST/PUT/PATCH) | - | | --timeout | - | Per-request timeout (ms) | 5000 | | --json | - | Output results as JSON | false | | --report-file | - | Path to write JSON report file | - | | --status-as-throttle | - | Status code to count as throttled | 429 | | --tag | - | Optional label/tag for the test run | - | | --config | - | Path to config file (JSON) | - | | --version | - | Show version number | - | | --help | -h | Show help message | - |

Config File Support

You can use a JSON config file to store default settings:

api-throttle.config.json:

{
  "url": "https://api.example.com/endpoint",
  "method": "GET",
  "total": 500,
  "concurrency": 25,
  "delay": 50,
  "timeout": 10000,
  "headers": {
    "Authorization": "Bearer your-token",
    "X-API-Key": "your-key"
  },
  "throttleStatus": 429,
  "tag": "production-test"
}

Then run:

api-throttle-tester --config api-throttle.config.json

CLI flags will override config file values.

Output Format

Human-Readable Table (Default)

============================================================
API Throttle Test Results
============================================================

Configuration:
  URL: https://api.example.com/endpoint
  Method: GET
  Total Requests: 100
  Concurrency: 10
  Delay: 0ms
  Timeout: 5000ms
  Throttle Status: 429

Summary:
  Successful (2xx): 82
  Throttled: 12
  Errors: 6
  Network Errors: 0
  Total: 100

Latency:
  Average: 135.42ms
  Min: 40.00ms
  Max: 800.00ms

Status Code Breakdown:
  200: 82
  429: 12
  500: 6

Latency Distribution:
  < 100ms:    15
  100-250ms:  40
  250-500ms:  25
  500-1000ms: 18
  > 1000ms:   2

============================================================

JSON Output

When using --json, the output is a structured JSON object:

{
  "url": "https://api.example.com/endpoint",
  "method": "GET",
  "tag": "optional-tag",
  "config": {
    "totalRequests": 100,
    "concurrency": 10,
    "delayMs": 0,
    "timeoutMs": 5000,
    "throttleStatus": 429
  },
  "summary": {
    "success": 82,
    "throttled": 12,
    "errors": 6,
    "networkErrors": 0,
    "avgResponseMs": 135.42,
    "minResponseMs": 40,
    "maxResponseMs": 800
  },
  "statusCounts": {
    "200": 82,
    "429": 12,
    "500": 6
  },
  "latencyBuckets": {
    "<100": 15,
    "100-250": 40,
    "250-500": 25,
    "500-1000": 18,
    ">1000": 2
  }
}

Examples

Example 1: Basic Load Test

api-throttle-tester https://jsonplaceholder.typicode.com/posts/1

Example 2: Testing Rate Limits

api-throttle-tester https://api.example.com/endpoint \
  -t 200 \
  -c 20 \
  --tag "rate-limit-test"

Example 3: POST Request with Authentication

api-throttle-tester https://api.example.com/users \
  -X POST \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -b '{"name":"Test User","email":"[email protected]"}'

Example 4: CI/CD Integration

api-throttle-tester https://api.example.com/health \
  --json \
  --report-file test-results.json \
  -t 1000 \
  -c 50

Then parse the JSON in your CI pipeline to check thresholds.

Example 5: Custom Throttle Detection

api-throttle-tester https://api.example.com/endpoint \
  --status-as-throttle 503 \
  -t 500

Development

Prerequisites

• Node.js 18+
• npm (or pnpm/yarn)

Setup

# Clone the repository
git clone https://github.com/yourusername/api-throttle-tester.git
cd api-throttle-tester

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linter
npm run lint

Project Structure

api-throttle-tester/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── cli.ts            # Command parsing
│   ├── runner/
│   │   └── loadTester.ts # Core load testing engine
│   ├── types/
│   │   └── index.ts      # TypeScript types
│   └── utils/
│       ├── config.ts     # Config file handling
│       ├── logger.ts     # Logging utilities
│       ├── metrics.ts    # Metrics calculation
│       └── output.ts     # Output formatting
├── tests/
│   ├── runner/
│   └── utils/
├── package.json
├── tsconfig.json
└── README.md

Testing

The project includes comprehensive tests:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

Responsible Usage

⚠️ Important: This tool is designed for testing your own APIs or APIs you have explicit permission to test.

• Do NOT use this tool to DDoS or attack third-party services
• Do NOT test APIs without proper authorization
• Always respect rate limits and terms of service
• Start with low concurrency and gradually increase
• Use appropriate delays to avoid overwhelming servers
• Be mindful of the impact on production systems

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, feature requests, or questions, please open an issue on GitHub.