---
name: api-tester
description: Generate ready-to-run cURL commands, HTTPie requests, and API client code snippets for any REST or GraphQL API — with correct auth headers, request bodies, and output formatting.
---

## Trigger Phrases
Use this skill when the request involves constructing an API request or testing an endpoint:

- "Give me a cURL command to call the GitHub API to list open PRs."
- "How do I authenticate to the Prometheus API with a Bearer token?"
- "Generate a curl to hit the Slack webhook with a formatted message."
- "Convert this API call to Python requests."
- "Write a cURL to test my Alertmanager webhook."
- "How do I call the AWS EC2 API to list running instances?"

Do not use this skill for SDK-based integrations that require a full library setup. Use for one-shot HTTP request construction.

## Deterministic Execution Flow

### Stage 0: Classify Output Type

| Mode | User intent | Deliverable |
|------|-------------|-------------|
| `curl` | Quick terminal test | Complete `cURL` command with all flags |
| `python` | Python `requests` implementation | Function with error handling and type hints |
| `go` | Go `net/http` client | Function with struct and error wrapping |
| `httpie` | HTTPie (human-friendly cURL alternative) | `http` command with correct syntax |
| `explanation` | Understand an existing API call | Break down headers, auth, body, expected response |

Default to `curl` if no language preference is stated.

### Stage 1: Collect Request Details
Identify or ask for:

| Field | Required | Notes |
|-------|----------|-------|
| API name / base URL | Yes | e.g., `api.github.com`, `localhost:9090` |
| HTTP method | Yes | GET, POST, PUT, PATCH, DELETE |
| Endpoint path | Yes | e.g., `/repos/{owner}/{repo}/pulls` |
| Authentication type | Yes | Bearer token, Basic auth, API key header, OAuth2, AWS SigV4 |
| Request body (if POST/PUT) | Conditional | JSON schema or example |
| Required query parameters | Conditional | e.g., `state=open`, `per_page=50` |
| Output format preference | Optional | Raw JSON, piped to `jq`, table |

For well-known APIs (GitHub, Slack, PagerDuty, Prometheus, Alertmanager, AWS), apply known API conventions without asking.

### Stage 2: Auth Pattern Reference

| Auth type | cURL implementation |
|-----------|-------------------|
| Bearer token (env var) | `-H "Authorization: Bearer ${TOKEN}"` |
| Basic auth (env var) | `-u "${USER}:${PASS}"` or `-H "Authorization: Basic $(echo -n $USER:$PASS | base64)"` |
| API key header | `-H "X-API-Key: ${API_KEY}"` |
| GitHub PAT | `-H "Authorization: token ${GITHUB_TOKEN}"` or `-H "Authorization: Bearer ${GITHUB_TOKEN}"` |
| AWS SigV4 | Use `aws-curl` or `awscurl`; note that raw cURL requires manual signing |
| No auth | No auth header; note if the endpoint should require auth (flag as security concern) |

**Rule:** Credentials are always environment variables in generated commands. Never generate a command with a literal token value.

### Stage 3: Common API Patterns

**GitHub REST API:**
```bash
curl -s \
  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/{owner}/{repo}/pulls?state=open&per_page=50" \
  | jq '[.[] | {number: .number, title: .title, author: .user.login}]'
```

**Slack Webhook:**
```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"text": "Alert: '"${MESSAGE}"'"}' \
  "${SLACK_WEBHOOK_URL}"
```

**Prometheus API:**
```bash
curl -s \
  "http://localhost:9090/api/v1/query?query=${PROMQL_QUERY}" \
  | jq '.data.result[]'
```

**Alertmanager Webhook (test):**
```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '[{"labels":{"alertname":"TestAlert","severity":"critical"},"annotations":{"summary":"Test alert"}}]' \
  "http://localhost:9093/api/v1/alerts"
```

### Stage 4: Output Format
Present the command with:

```
## API Request: [API name] — [What it does]

**Auth required:** [type]
**Environment variables needed:**
- `VARIABLE_NAME` — [what it is]

**Command:**
\`\`\`bash
[complete command]
\`\`\`

**Expected response:**
[HTTP status code and what the body looks like on success]

**Common failure cases:**
- 401 → [auth issue explanation]
- 403 → [permission issue explanation]
- 404 → [resource not found / wrong path]
```

For Python/Go output, include a docstring or function comment explaining the purpose and return type.

## Done Criteria
- Credentials are always environment variables, never hardcoded literals.
- The command is complete and runnable without modification (except filling in env vars).
- For well-known APIs, correct auth headers and API version headers are applied.
- Output includes expected success response format.
- Common failure cases (401, 403, 404) are explained.
- `jq` filtering is included when the raw API response is large or nested.