How-to: Add a New Endpoint
You’ve got a new feature idea and need an API route that feels right at home next to /api/feed. Here’s the playbook we use: start with validation, keep the handler tiny, and lean on Supabase for auth.
Goal
Add a GET endpoint that greets the reader by name—simple enough to grok, but it shows the zod + Supabase pattern we reuse everywhere.
Steps
- Create the handler file under
web/src/app/api/hello/route.ts.
import { z } from 'zod';
import type { NextRequest } from 'next/server';
const Query = z.object({
name: z.string().trim().min(1).default('world'),
});
export async function GET(req: NextRequest) {
const { searchParams } = new URL(req.url);
const parsed = Query.safeParse({ name: searchParams.get('name') ?? undefined });
if (!parsed.success) {
return Response.json({ error: 'Invalid query' }, { status: 400 });
}
return Response.json({ msg: `Hello, ${parsed.data.name}!` });
}
That structure mirrors our production handlers: parse input, bail fast if invalid, return JSON.
- Smoke test with curl (or HTTPie if that’s your vibe).
curl -sS "http://localhost:3000/api/hello?name=HUD" | jq .
You should see:
{"msg":"Hello, HUD!"}
Pitfalls to dodge
- Skip validation and you’ll eventually ship a handler that trusts
req.json()blindly. Stick with zod. - Never instantiate the Supabase admin client in a client component. Server-only secrets (service role, Gemini fallback) stay inside API routes.
Time estimate
5–10 minutes, depending on how fancy your response payload needs to be.