Route Handlers

🔍 What Is It?

Route Handlers are server-side request handlers defined in route.ts files inside app/:

• →File: app/api/products/route.ts
• →URL: /api/products
• →Exports: Named functions matching HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• →API: Web standard Request and Response objects (not Node.js req/res)

Key differences from Pages Router API routes:

• →Use NextRequest / NextResponse (extended Web API)
• →Support streaming responses
• →Can run on Edge Runtime
• →Support all HTTP methods with named exports
• →Can be co-located with the route they serve

🎯 Why Do We Need It?

Route Handlers are needed for:

• →External API consumers — mobile apps, third-party integrations
• →Webhooks — receiving events from Stripe, GitHub, CMS
• →Form submissions — when not using Server Actions
• →File uploads — handling multipart form data
• →OAuth callbacks — handling redirect-based auth flows
• →Streaming responses — Server-Sent Events, streaming AI responses

For internal data fetching from Server Components, you do NOT need Route Handlers — fetch directly from the DB.

🏗️ What Happens in Real Projects?

Route Handler use cases in production:

app/api/
├── webhooks/
│   ├── stripe/route.ts      # Stripe payment webhooks
│   └── github/route.ts      # GitHub CI/CD webhooks
├── revalidate/route.ts      # CMS revalidation webhook
├── upload/route.ts          # File upload endpoint
├── auth/
│   └── [...nextauth]/route.ts # NextAuth handler
└── products/
    ├── route.ts             # GET /api/products, POST /api/products
    └── [id]/route.ts        # GET/PUT/DELETE /api/products/:id

⚙️ How It Works

Route Handler request lifecycle:

1. HTTP request arrives at /api/products
2. Next.js matches app/api/products/route.ts
3. Calls the exported function matching the HTTP method (GET, POST, etc.)
4. Function receives NextRequest and a context object with params
5. Function returns a NextResponse or plain Response
6. Response is sent to the client

Caching: GET Route Handlers are cached by default in Next.js 14. In Next.js 15, they are not cached by default. Use export const dynamic = 'force-dynamic' to opt out of caching.

💻 Example

Route Handler Patterns — CRUD Route Handler with auth, validation, and error handling.

// app/api/products/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/db';
import { requireAuth } from '@/lib/auth';
import { z } from 'zod';

const CreateProductSchema = z.object({
  name: z.string().min(1),
  price: z.number().positive(),
  category: z.string(),
});

// GET /api/products
export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const category = searchParams.get('category');

  const products = await db.product.findMany({
    where: category ? { category } : undefined,
    orderBy: { createdAt: 'desc' },
  });

  return NextResponse.json(products);
}

// POST /api/products
export async function POST(request: NextRequest) {
  // Auth check
  const session = await requireAuth(request);
  if (!session) {
    return NextResponse.json({ error: 'Unauthorised' }, { status: 401 });
  }

  // Parse and validate body
  const body = await request.json();
  const result = CreateProductSchema.safeParse(body);
  if (!result.success) {
    return NextResponse.json(
      { error: 'Validation failed', issues: result.error.issues },
      { status: 400 }
    );
  }

  const product = await db.product.create({ data: result.data });
  return NextResponse.json(product, { status: 201 });
}

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits