api-health-pipeline

A CLI tool that discovers, tests, benchmarks, and generates beautiful visual health reports for REST API endpoints.

What It Does

Point it at a list of URLs or an OpenAPI spec, and it runs a complete pipeline:

• Connectivity checks — Verify endpoints are reachable
• Response time analysis — Percentiles (p50, p95, p99)
• Status code tracking — Success/error rates
• Payload size monitoring — Request/response sizes
• Header validation — Check required headers
• Redirect chain tracing — Follow and analyze redirects

Outputs a color-coded terminal dashboard + self-contained HTML report with charts. No paid services, no API keys required.

Installation

npm install -g api-health-pipeline

Or use directly:

npx api-health-pipeline

Quick Start

From a URL list

api-health-pipeline --urls https://api.example.com/health,https://api.example.com/users

From an OpenAPI spec

api-health-pipeline --spec openapi.json

From a file

api-health-pipeline --file endpoints.txt

With custom options

api-health-pipeline --urls https://api.example.com/health \
  --requests 50 \
  --timeout 10000 \
  --output ./reports

Options

Flag	Description	Default
--urls	Comma-separated endpoint URLs	—
--spec	Path to OpenAPI/Swagger spec file	—
--file	Path to text file with one URL per line	—
--requests	Number of requests per endpoint	20
--timeout	Request timeout in milliseconds	5000
--output	Report output directory	./health-reports
--headers	JSON file with custom headers	—
--concurrency	Parallel requests	5

Output

Terminal Dashboard

Real-time color-coded summary with:

• Endpoint status (✓ healthy, ✗ down, ⚠ slow)
• Response time ranges
• Error rates
• Payload sizes

HTML Report

Self-contained report with:

• Response time distribution charts
• Status code breakdowns
• Uptime timeline
• Header validation results
• Redirect analysis

Examples

Test 3 endpoints, 100 requests each:

api-health-pipeline --urls https://api.example.com/v1/health,https://api.example.com/v1/users,https://api.example.com/v1/posts --requests 100

Load from OpenAPI spec with custom headers:

api-health-pipeline --spec api.json --headers auth.json --output ./my-reports

High concurrency benchmark:

api-health-pipeline --file endpoints.txt --concurrency 20 --requests 200

FAQ

Q: Does it require authentication?
A: Yes, use the --headers flag to pass a JSON file with auth tokens or custom headers.

Q: Can I test POST/PUT endpoints?
A: Currently supports GET requests. POST/PUT support coming soon.

Q: How long does a full pipeline run?
A: Depends on endpoint count and request volume. 20 endpoints × 20 requests typically takes 2-5 minutes.

Q: Can I schedule regular health checks?
A: Yes, wrap it in a cron job or CI/CD pipeline. Reports are timestamped.

Q: What if an endpoint is down?
A: It's marked as down in the report with error details. The pipeline continues testing other endpoints.

Q: Can I customize the HTML report?
A: The report is self-contained. You can edit the output HTML directly or request custom styling.

---

Built with AI by Craftpipe
Support: support@heijnesdigital.com