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

  1. 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.

  1. 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.