api-validation

API Route Validation Rules

RULE 1: NEVER Access Request Body Without Zod Validation

Unvalidated request bodies are the #1 source of runtime crashes and injection vulnerabilities. Every API route MUST validate the incoming body with Zod before any processing.

✅ CORRECT — validate first:

import { z } from 'zod'
import { NextRequest, NextResponse } from 'next/server'

const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1).max(10000),
  published: z.boolean().default(false),
})

export async function POST(request: NextRequest) {
  const body = await request.json()

  const result = CreatePostSchema.safeParse(body)
  if (!result.success) {
    return NextResponse.json(
      { error: 'Invalid request', details: result.error.flatten() },
      { status: 400 }
    )
  }

  const { title, content, published } = result.data
  // Now safe to use
}

❌ WRONG — raw body access:

export async function POST(request: NextRequest) {
  const { title, content } = await request.json() // No validation — crashes on missing fields
  // title could be undefined, an object, a number — anything
}

RULE 2: Validate Server Action Parameters With Zod

Server Actions receive untyped FormData or direct calls — always validate.

✅ CORRECT:

'use server'
import { z } from 'zod'

const UpdateProfileSchema = z.object({
  name: z.string().min(1).max(100),
  bio: z.string().max(500).optional(),
})

export async function updateProfile(data: unknown) {
  const result = UpdateProfileSchema.safeParse(data)
  if (!result.success) {
    return { error: result.error.flatten().fieldErrors }
  }
  // Process result.data safely
}

RULE 3: Always Return Consistent Error Shapes

API routes must return a consistent error shape: { error: string, details?: unknown }. Never expose raw error messages, stack traces, or database errors to the client.

✅ CORRECT:

try {
  // ... operation
} catch (error) {
  console.error('[API_ERROR]', error) // Log server-side only
  return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
}