api-design

API design: route handlers, server actions, services

Choosing the mechanism

• Server component rendering static/one-shot data → call the service directly. No HTTP hop.
• Data a client component reads (refetched, paginated, mutated, shared) → server action used as the queryFn of a TanStack Query queryOptions factory (see the tanstack-query skill).
• Mutations from your own UI → server action, wrapped in useMutation when called from a client component (cache invalidation), or useActionState for plain RSC forms.
• Endpoint consumed by external clients / mobile / webhooks → route handler. Also switch a read to a GET route handler when it needs HTTP/CDN caching or parallel requests (server actions serialise).
• Never build a route handler just so your own client component can fetch it — the action-as-queryFn pattern covers that.

Route handler shape (thin)

src/app/api/<resource>/route.ts:

import { NextResponse } from 'next/server'
import { createUserSchema } from '@/modules/users/schemas/user'
import { createUser } from '@/modules/users/services/create-user'

export async function POST(req: Request) {
  const body = await req.json().catch(() => null)
  const parsed = createUserSchema.safeParse(body)
  if (!parsed.success) {
    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 })
  }
  const result = await createUser(parsed.data)
  if (!result.ok) {
    return NextResponse.json({ error: result.error }, { status: result.status })
  }
  return NextResponse.json(result.data, { status: 201 })
}

Pattern: parse → authorize → call service → map result to response. Under ~30 lines; anything more belongs in the service.

Server actions

• File-level 'use server' in modules/<feature>/actions.ts.
• Every action validates input with Zod and checks auth itself — server actions are public HTTP endpoints regardless of where the button lives.
• Return shape depends on the caller:
  • Used as a TanStack Query queryFn/mutationFn → return the plain DTO and throw on failure (Query needs a rejected promise for its error state).
  • Called from useActionState → return typed results ({ ok: true, data } | { ok: false, error }), don't throw for expected failures.
• After a mutation: revalidatePath/revalidateTag if RSC-rendered data changed; the client-side invalidateQueries happens in the mutation's onSuccess, not here.