Api Workbench

SKILL.md

---
name: api-workbench
display_name: API Workbench
description: Command-line API debugging tool with natural language requests, curl parsing, assertions, collection runner, and API documentation generation.
author: harry
version: 1.0.0
license: MIT
type: skill
tags:
  - api
  - http
  - debugging
  - developer-tools
  - testing
model: deepseek
created_at: 2026-06-14
---

# 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

```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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