api-console

A signed-in API test console for peteshepley.com's APIs: pick an API from the dropdown, browse its OpenAPI documentation, and try out live requests against your own data. TypeScript, React, and Vite, authenticated with Clerk.

For why things are built this way, and how the deployment infra fits together, see the build journal in the sibling operations repo: operations/docs/projects/api-console/journal.md.

Structure

src/
  apis.ts       Registry of testable APIs — add an entry to add a new API to the dropdown
  App.tsx       Header (auth), API dropdown, SwaggerUI panel
  main.tsx      ClerkProvider setup

Each entry in apis.ts points at a published OpenAPI spec (openapiUrl, hosted on peteshepley.com's /api-docs page — see that repo) and a Clerk JWT template name (clerkJwtTemplate) used to mint a bearer token for that API's "Try it out" requests.

Commands

Command	Action
npm install	Install dependencies
npm run dev	Start dev server at localhost:5173
npm run build	Type-check + build to ./dist/
npm run preview	Preview the production build locally
npm run lint	Lint (oxlint)

Local setup

Copy .env.example to .env.local and set VITE_CLERK_PUBLISHABLE_KEY to the publishable key of the Clerk application resume-api (and other tested APIs) trust — see operations/docs/runbooks/resume-api-deployment.md for where that application lives.

Adding an API to the dropdown

1. Publish its OpenAPI spec on peteshepley.com under /api-docs (see that repo's README).
2. Create a Clerk JWT template for it, if it needs one distinct from the existing ones (audience matching what that API's authorizer expects).
3. Add an entry to the apis array in src/apis.ts.

Deployment

Deploys via GitHub Actions on every push to main (.github/workflows/deploy.yml): build the app, sync dist/ to the peteshepley-api-console-site S3 bucket, invalidate CloudFront. Authentication is via GitHub OIDC (no stored AWS credentials) — the role, bucket, and CloudFront distribution are provisioned in operations/infra/apps/api-console. Pull requests run .github/workflows/ci.yml (type-check + build) without touching any deployment credentials.

Required repo configuration (see operations/docs/runbooks/api-console-deployment.md for how to get these values):

Name	Kind	Value
AWS_ROLE_ARN	Actions secret	tofu output github_deploy_role_arn in operations/infra/apps/api-console
CLOUDFRONT_DISTRIBUTION_ID	Actions variable	tofu output cloudfront_distribution_id in operations/infra/apps/api-console
VITE_CLERK_PUBLISHABLE_KEY	Actions variable	Clerk application's publishable key (not sensitive — it's shipped to the browser)

Live at test.peteshepley.com.