API Testing

Testing an API means proving that an endpoint behaves correctly across the cases that matter: the happy path, auth boundaries, bad input, and idempotency. The goal isn't to hit every URL once — it's to encode the contract of each endpoint as checks that fail loudly when the contract breaks.

Workflow

1. Discover the surface. Find the endpoints worth testing. Look in

app/api/, pages/api/, route handlers, Supabase RPC functions, and any Stripe webhook handler. Ask the user for the base URL (local dev vs. the live Vercel URL) and any auth token / API key needed. Never hard-code secrets into the suite file — reference environment variables instead.

1. Write a suite file. Express the tests as a JSON suite (schema below). One

entry per case. Cover, per endpoint:

• Happy path — valid request returns the expected status and body shape.
• Auth boundary — the same request without a token (or with a wrong one)

is rejected. For Supabase, this is where you catch missing RLS policies.

• Validation — malformed/missing fields return 4xx, not 500.
• Idempotency — for payment/booking creation, the same idempotency key

doesn't double-charge or double-book.

• Webhooks — a payload with a bad/missing signature is rejected; a valid

one is accepted exactly once.

1. Run it with the bundled runner — it needs no dependencies (Python stdlib):

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/api/run_suite.py <suite.json>

Set referenced secrets in the environment first, e.g. export AUTH_TOKEN=... STRIPE_KEY=.... The runner substitutes ${VAR} in the suite at request time.

1. Report. Summarize pass/fail per case. For failures, show the expected vs.

actual status and the relevant body fragment so the cause is obvious. Treat a 500 on a validation case as a real bug, not a pass.

Suite schema

{
  "base_url": "${BASE_URL}",
  "defaults": { "headers": { "Content-Type": "application/json" } },
  "cases": [
    {
      "name": "create booking — happy path",
      "method": "POST",
      "path": "/api/bookings",
      "headers": { "Authorization": "Bearer ${AUTH_TOKEN}" },
      "body": { "listingId": "abc", "checkIn": "2026-07-01", "checkOut": "2026-07-05" },
      "expect": { "status": 201, "json_has": ["id", "status"], "json_match": { "status": "pending" } }
    },
    {
      "name": "create booking — rejects unauthenticated",
      "method": "POST",
      "path": "/api/bookings",
      "body": { "listingId": "abc" },
      "expect": { "status_in": [401, 403] }
    }
  ]
}

Supported assertions in expect: status (exact), status_in (list), json_has (keys that must exist, dot-paths allowed), json_match (exact key/value pairs), body_contains (substring), max_ms (latency ceiling).

For deeper guidance

When testing Stripe webhooks, RLS edge cases, or idempotency in depth, read references/patterns.md for worked examples specific to the Supabase + Stripe stack.

When to hand off to the agent

For a broad sweep ("test the whole API"), delegate to the api-test-runner agent — it discovers endpoints, drafts the suite, runs it, and returns a report, keeping the discovery file-dumps out of the main conversation.