apitest — API QA (master)

This skill acts as master in a master / worker pattern for large workloads: it plans, sequences, holds secrets policy, merges outcomes. Delegate narrow, independent slabs to worker runs (parallel Cursor agents or separate chat tasks) — never fork without a stable BASE_URL, mode, and credential contract.

Always compose devenv for infra + deployment mode before HTTP unless endpoints are confirmed up.

0. Prerequisites (delegation)

1. devenv phase — user intent (host API / consumer / temporal_worker / local / full compose), .env* hygiene, MAX_ROUNDS verify loop GREEN.
2. Base URL — default http://127.0.0.1:8080; path prefix /v1 (see CLAUDE.md/AGENTS.md — no trailing slash on base).
3. Trust model — user runs commands on their machine only; orchestrator prefers stdin env injection for curls not logging raw secrets.

1. Interactive credential ritual (blocking questions)

Ask explicitly, one bundle at a time:

Operational rule: Prefer shell:

read -rs FLEXPRICE_TEST_API_KEY && export FLEXPRICE_TEST_API_KEY && export BASE_URL=http://127.0.0.1:8080 && …

Never paste full keys back in assistant prose — confirm present/absent/length fingerprint only.

2. Minimal curl toolchain

# Health (normally unauthenticated outer router — GET /health is root router; swagger says /v1 base for API)
curl -sfS "${BASE_URL:-http://127.0.0.1:8080}/health" | head -c 200 || echo FAIL

# Private v1 example skeleton
curl -sfS "${BASE_URL:-http://127.0.0.1:8080}/v1/some/route" \
  -H "x-api-key: ${FLEXPRICE_TEST_API_KEY}" \
  ${FLEXPRICE_TEST_ENV_ID:+-H "X-Environment-ID: ${FLEXPRICE_TEST_ENV_ID}" } \
  -H "Accept: application/json"

Adapt routes from docs/swagger/ (swagger-3-0.json / handler paths in internal/api/router.go).

Verb matrix: -f curls fail on 4xx/5xx — toggle -w '\n%{http_code}\n' when debugging semantics.

Large bodies: --data-binary @file.json plus -H 'Content-Type: application/json'.

3. Standard orchestration playbook (deterministic phases)

Tick mentally as Orchestrator:

[A] Requirement intake — verbs (GET invoice? POST event?), tenancy surface, destructive vs readonly
[B] Compose **devenv** — mode + infra + verify loop GREEN
[C] Credential interactive gather — §1 vars exported in user shell orchestrator echoes
[D] Smoke ladder — health → simplest GET → progressively complex POST
[E] Record actual HTTP codes + trimmed JSON excerpts (truncate >2KB bodies)
[F] Tear-down optional — advise user Ctrl-C server / docker stop if ephemeral

Consumer mode caveat: consumer / ingestion-only modes expose few/no HTTP tests meaningful — steer user to api or local for REST probes while consumer runs sibling process.

4. Master / worker decomposition (massive workflows)

When splitting is justified:

• > ~8 independent endpoints without shared mutable side-effect ordering.
• Geography across Swagger tags (Customers, Invoices, Events, …).

Orchestrator tasks:

Worker tasks:

Mechanism hints (implementation-agnostic wording for Cursor stacks):

• Use multiple parallel agent runs (background tasks) when product UI supports partitioning — isolate prompts — avoid shared file edits concurrently on identical paths.
• If only single agent lane: sequential micro-batches respecting DAG.

Workers pull infra state from devenv completion note (BASE_URL GREEN).

Anti-pattern:** workers independently restart docker / rewrite .env — Orchestrator only.

5. Automated depth tiers

6. Failure triage playbook

Attach Correlation: request IDs from logging middleware (internal/rest/middleware).

7. Combining with Temporal / queues

Pure HTTP probes cannot finalize Metering completeness — annotate defer validation (ClickHouse/dashboard) referencing docs/FLOWS/event-processing.md.

Temporal heavy flows: optionally poll Temporal UI human step — mark automate-later.

8. Forbidden actions

• Storing echoed secrets in markdown docs / repo commits.
• Production curls without explicit dual opt-in (user typed target twice).
• Bypassing RBAC intentional brute force — escalate with user instead.

Cross-links

The master orchestrator stance: keep this file thin on endpoint enumeration (Swagger is source) — prioritize interaction contract + safety + parallelism rules.