Route Handlers & API Routes

Next.js provides built-in API endpoint capabilities so you can build your backend alongside your frontend without a separate server.

Route Handlers (App Router)

In the App Router, API endpoints are defined in route.ts (or route.js) files that export functions named after HTTP methods:

// app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.users.findMany();
  return Response.json(users);
}
 
export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return Response.json(user, { status: 201 });
}

Supported methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Unsupported methods return 405 Method Not Allowed automatically.

Route handlers use the standard Web API Request and Response objects — not the Node.js-specific req/res from Pages Router. This makes them compatible with edge runtime and standard across platforms.

Dynamic Route Handlers

Dynamic segments work the same as pages: app/api/users/[id]/route.ts receives params as the second argument:

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const user = await db.users.findById(id);
  if (!user) return Response.json({ error: 'Not found' }, { status: 404 });
  return Response.json(user);
}

In Next.js 15+, params is a Promise that must be awaited.

Caching Behavior

GET route handlers are cached by default when they don't read the request (no request parameter usage, no dynamic functions). To opt out:

• Use the request object (reading headers, cookies, searchParams)
• Export const dynamic = 'force-dynamic'
• Use other dynamic functions

POST, PUT, PATCH, and DELETE handlers are never cached.

Streaming Responses

Route handlers support streaming with ReadableStream:

export async function GET() {
  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue(new TextEncoder().encode('data: hello\n\n'));
      controller.close();
    }
  });
  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
}

This enables Server-Sent Events (SSE), chunked responses, and AI streaming patterns.

Route Handlers vs Server Actions

Server Actions ('use server' functions) handle mutations triggered from the UI — form submissions, button clicks, data updates. Route Handlers serve external API consumers, webhooks, and endpoints that need standard HTTP semantics (status codes, headers, content negotiation).

Use Server Actions for: form submissions, UI-triggered mutations, optimistic updates. Use Route Handlers for: external API consumers, webhooks, authentication callbacks, file downloads, SSE/streaming.

Pages Router API Routes (Legacy)

The Pages Router uses pages/api/ directory with Node.js-style handler functions: export default function handler(req, res) { res.status(200).json({ data }) }. These use NextApiRequest/NextApiResponse — Node.js-specific APIs not compatible with edge runtime. New projects should use App Router route handlers.

Key Interview Distinction

Route handlers are route.ts files exporting HTTP method functions (GET, POST, etc.) using standard Web Request/Response APIs. They run only on the server, support streaming, and can run at the edge. GET handlers are cached by default unless they read dynamic request data. Use Route Handlers for external APIs and webhooks; use Server Actions for UI-triggered mutations.