api-validation

API Validation

Scope

HTTP endpoint validation for REST, GraphQL (over HTTP), JSON-RPC, and webhook receivers. Does NOT handle frontend (use web-validation), fullstack orchestration (use fullstack-validation), or contract-schema testing for non-HTTP (use custom harness).

Preflight

• Server responds at expected port (curl -sf http://localhost:PORT/health)
• DB reachable (pg_isready, redis-cli ping, etc.)
• Required env vars present (API keys, DB URL, JWT secret)
• Migrations current

Execution Patterns

# Happy path
curl -s -X POST http://localhost:3000/api/resource \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}' \
  | tee e2e-evidence/vgN-happy.json | jq .

# Status-only (check status code behavior)
curl -s -o e2e-evidence/vgN-unauth.json \
  -w "%{http_code}\n%{time_total}\n" \
  -X POST http://localhost:3000/api/resource \
  > e2e-evidence/vgN-unauth-meta.txt

# Error path
curl -s -X POST http://localhost:3000/api/resource \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invalid":"payload"}' \
  | tee e2e-evidence/vgN-invalid.json

# Verify DB side effect
psql "$DATABASE_URL" -c "SELECT * FROM resource WHERE name='example'" \
  | tee e2e-evidence/vgN-db.txt

PASS Criteria Patterns

Good:

• "Response JSON has id non-null AND name == 'example' AND NO password field"
• "Unauthenticated POST returns 401"
• "Invalid payload returns 400 with error.field == 'name'"
• "p95 latency < 200ms over 100 requests"
• "DB row count increased by exactly 1"

Bad (reject):

• "Endpoint works" → which one, what inputs?
• "Returns 2xx" → specify: 200 or 201? empty body counts?
• "Security is fine" → specific: what unauth case? what JWT tampering?

Gate Template

<validation_gate id="VG-N" blocking="true" platform="api"
                 protocol="functional-validation"
                 platform_skill="api-validation"
                 verdict_by="gate-validation-discipline">
  <preflight skill="preflight">[server + DB + env ready]</preflight>
  <execute>[curl sequences covering happy + auth + validation + idempotency]</execute>
  <capture>[response JSON + status + headers to e2e-evidence/vgN-*]</capture>
  <pass_criteria>[specific jq-checkable assertions]</pass_criteria>
  <review>[jq -e expressions; grep for specific status codes]</review>
  <verdict>PASS → next | FAIL → error-recovery → re-run</verdict>
  <mock_guard skill="no-mocking-validation-gates">
    Real DB, real API. No supertest against mock app, no in-memory DB.
  </mock_guard>
</validation_gate>

Required Coverage Per Endpoint

Every endpoint validated by a gate MUST cover:

• Happy path (valid input, authenticated) → expected status + body
• Unauthenticated / invalid token → 401 or 403 with no leak
• Invalid payload → 400 with actionable error
• DB side effect verified independently (SELECT, not just API round-trip)

For idempotent endpoints:

• Duplicate request → same response, no duplicate side effect

For paginated endpoints:

• Page 2 returns distinct rows from page 1
• total / hasMore fields reflect truth

Common Failure Patterns

Symptom	Likely cause	Fix
200 OK with error body	Handler swallowed exception	Check handler; use 4xx for client errors
500 with no log	Stack trace suppressed in prod	Check log level; add structured error logger
CORS preflight fails	OPTIONS handler missing	Add explicit OPTIONS or use cors middleware
Timing-attack on auth	Compare-time differs for valid vs invalid	Use constant-time compare

Rules

1. Always hit real server — never use supertest against mock app
2. Always read response body — status code alone is insufficient
3. Always verify DB side effect independently
4. Always cover error paths — happy-path-only = shipping bugs

Security Policy

Never log or commit evidence containing real tokens, API keys, or PII. Use test tokens; rotate after evidence capture.