Api Workbench

Command-line API debugging tool with natural language requests, curl parsing, assertions, collection runner, and API documentation generation.

API Workbench (api-workbench)

A terminal-native API debugging tool. Send HTTP requests, validate responses, chain multiple requests with variable passing, and generate API docs — all from the command line.

Supports three input modes: natural language, curl command import, and OpenAPI/Swagger spec import (JSON format only; YAML requires optional PyYAML).

Quick Start

clawhub run api-workbench "GET https://jsonplaceholder.typicode.com/posts/1"

This sends an HTTP GET request and displays a formatted response with status, headers, body, timing, and equivalent curl command.

Features

Feature	Description
Multi-mode Input	Natural language, curl command, OpenAPI import, manual
Full HTTP Support	GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS
Request Components	Headers, query/path params, JSON/form/text/file body, auth
Response Analysis	Status, headers, body (auto-formatted JSON), timing, size
Assertions	Status range, JSON Schema, header check, response time
Collection Runner	Multi-request chains with variable passing and data-driven execution
API Doc Generation	Auto-generate Markdown API docs from requests/responses
History & Favorites	Auto-save last 100 requests, searchable and re-runnable
SSRF Protection	Blocks requests to internal/private addresses by default

Sample Prompts

Prompt 1: Natural Language Request

clawhub run api-workbench "Get user list from https://api.example.com/users?page=1"

Expected output:

═══════════════════════════════════════
GET https://api.example.com/users?page=1
═══════════════════════════════════════
Status: 200 OK  ⏱ 127ms  📦 4.2 KB
Headers:
  Content-Type: application/json
  X-RateLimit-Remaining: 98
Body:
{
  "data": [...],
  "total": 150,
  "page": 1
}
curl: curl -X GET 'https://api.example.com/users?page=1'

Prompt 2: Curl Command Import

clawhub run api-workbench --curl "curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{\"username\":\"admin\",\"password\":\"secret\"}'"

Expected output: Parses curl into structured request → executes → shows response + test results.

Prompt 3: Collection Runner with Variables

clawhub run api-workbench --collection login-and-fetch.json

Expected output: Executes collection steps with variable passing:

✅ [1/2] POST /login → 200 OK (87ms)
✅ [2/2] GET /profile → 200 OK (64ms) [token passed]
2 passed, 0 failed

Prompt 4: OpenAPI Import

clawhub run api-workbench --openapi ./petstore.json  (Note: only JSON format is natively supported; YAML requires optional PyYAML)

Expected output: Lists 15 discovered API endpoints, prompts user to select and test.

Prompt 5: Request with Assertions

clawhub run api-workbench "GET https://api.example.com/users" --expect-status 200 --expect-time < 500ms

Expected output: Request + assertion results with pass/fail for each check.

First-Success Path

Goal: First HTTP request within 5 seconds of installation.

Step 1: clawhub install api-workbench
Step 2: clawhub run api-workbench "GET https://jsonplaceholder.typicode.com/posts/1"
Step 3: Internal pipeline:
  a. nl_parser.py extracts method=GET, url=...
  b. request.py sends HTTP request
  c. response.py parses and formats
  d. formatter.py pretty-prints output
Step 4: User sees formatted request + response
Step 5: User copies the output curl command to share → first value

Architecture

api-workbench/
├── SKILL.md
├── scripts/
│   ├── request.py         # HTTP client (fetch/urllib)
│   ├── response.py        # Response parsing and formatting
│   ├── curl_parser.py     # Curl command parser
│   ├── nl_parser.py       # Natural language intent parser
│   ├── openapi.py         # OpenAPI/Swagger import
│   ├── assertions.py      # Assertion engine
│   ├── collection.py      # Collection Runner
│   ├── variables.py       # Variable passing and resolution
│   ├── history.py         # Request history management
│   ├── formatter.py       # Output formatter
│   ├── doc_generator.py   # API documentation generator
│   └── security.py        # Security module (SSRF, sanitization)
└── references/
    └── examples.json

Error Handling

Code	Scenario	Action
E001	Invalid URL	Format error + correct examples
E002	DNS failure	Network error + check suggestion
E003	Connection refused	Error + port/service status hints
E004	TLS cert invalid	Warning + --insecure option
E005	Request timeout	Timeout info + current timeout_ms config
E006	Response parse failure	Return raw body + parse error
E007	Curl parse failure	Syntax error with position
E008	OpenAPI parse failure	Schema validation error details
E009	Collection step failure	Continue/stop per config
E010	File upload not found	Path error
E011	NL intent unparsable	Suggest manual mode

Security

• Credentials never stored: Auth tokens/passwords not persisted in history
• SSRF protection: Blocks requests to 127.0.0.1/10.x/172.16-31.x/192.168.x by default
• Local execution: All requests from local machine, zero external data sharing
• Environment variables: Supports $ENV_VAR / ${ENV_VAR} syntax to avoid hardcoded secrets
• File upload size limit: Default max 50MB