Endpoint Validator Skill
Deterministic HTTP endpoint validation: discover config, test each endpoint against expectations, report pass/fail with CI-compatible exit codes.
Deep References
Load on demand when the signal matches.
| Signal | Reference | Content |
|---|---|---|
| Security header WARNs, HSTS/CSP/X-Frame | references/security-headers.md | Header checks, required values, remediation |
| Config errors, hardcoded IPs, timeouts | references/endpoint-config-preferred-patterns.md | Configuration failure modes and fixes |
| 401/403 failures, auth patterns | references/auth-endpoint-patterns.md | Bearer, API-key, cookie auth validation |
Instructions
Phase 1: DISCOVER
Read repository CLAUDE.md for base URL conventions or env var names.
Search for endpoint config in order: endpoints.json in project root,
tests/endpoints.json, inline specification from user. Prefer version-controlled
config over ad-hoc lists.
Config shape:
json{ "base_url": "http://localhost:8000", "endpoints": [ {"path": "/health", "expect_status": 200}, {"path": "/api/v1/users", "expect_key": "data", "timeout": 10}, {"path": "/api/v1/search?q=test", "max_time": 2.0} ] }
Endpoint fields: path (required), expect_status (default 200),
expect_key (top-level JSON key), timeout (default 5s), max_time (SLOW
threshold), method (default GET), headers (per-endpoint).
Rules:
- Warn before POST/PUT/DELETE against production base URLs.
- Use hostnames or
${ENV_VAR}inbase_url, not hardcoded IPs. - Confirm base URL reachable before the full suite.
Gate: config parsed, base URL reachable, at least one endpoint defined.
Phase 2: VALIDATE
Execute, do not reason. Run the request. Paste the exit code and output.
Test endpoints sequentially. For each:
- Send request with configured method and timeout.
- Check status code against
expect_status. Mismatch -> FAIL. - If
expect_keyset, parse JSON and check key exists. Missing/invalid -> FAIL. - If
max_timeset and elapsed exceeds it -> SLOW. - On non-localhost URLs, check security headers (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Missing -> WARN (not FAIL). Skip HSTS on HTTP-only base URLs. Skip X-Frame-Options if CSP has
frame-ancestors.
Failure handling: connection refused -> FAIL "Connection refused"; timeout -> FAIL "Timeout after Ns"; invalid JSON on expect_key -> FAIL "Invalid JSON response".
Gate: all endpoints tested, each has PASS/FAIL/SLOW verdict.
Phase 3: REPORT
Format:
ENDPOINT VALIDATION REPORT ========================== Base URL: http://localhost:8000 /api/health 200 OK 45ms /api/products 500 FAIL "Internal Server Error" /api/slow 200 SLOW 3.2s > 2.0s threshold SUMMARY: Passed 13/15 (86.7%), Failed 1, Slow 1
Exit 0 if all passed. Exit 1 if any failed.
Error Handling
| Error | Cause | Fix |
|---|---|---|
| Base URL unreachable | Wrong port or service down | ss -tlnp to confirm port |
| All endpoints timeout | Wrong host or proxy issue | curl -v a single endpoint |
JSON parse failure on expect_key | Non-JSON response (HTML/XML) | Remove expect_key or check Content-Type |
| FAIL on intentional 404 | Default expect_status is 200 | Set "expect_status": 404 |
| 401 on auth endpoint | Missing/expired credentials | Add auth header; see references/auth-endpoint-patterns.md |
CI Integration
bash# Pre-deployment gate with curl jq -r '.endpoints[].path' endpoints.json | while read path; do curl -sf "http://localhost:8000$path" > /dev/null || { echo "FAIL: $path"; exit 1; } done
