What is the difference between API Routes (Pages Router) and Route Handlers (App Router)? What new capabilities do Route Handlers have?

Question

Accepted Answer

Route Handlers are the App Router evolution of API Routes, offering a fundamentally different approach to building server-side endpoints. While API Routes were limited to the `/pages/api` directory and ran only in Node.js, Route Handlers leverage the file-system routing of the App Router—they can live anywhere in the `app` folder, not just under `/api`. More importantly, Route Handlers introduce capabilities that were impossible or complex with API Routes: streaming responses, Edge Runtime support, fine-grained cache control, and seamless integration with Next.js's caching layers. Location flexibility: API Routes only exist in `/pages/api`; Route Handlers can be defined anywhere in the `app` folder using `route.js` files, allowing co-location with related UI components. Runtime options: API Routes only support Node.js; Route Handlers support both Node.js and Edge runtimes, enabling ultra-fast responses from global edge locations. Caching capabilities: API Routes had no built-in caching; Route Handlers integrate with Next.js's full caching system, supporting `revalidate`, `tags`, and `fetch` cache options. Streaming support: Route Handlers can stream responses using web streams, enabling real-time data delivery and large file transfers; API Routes were limited to sending complete responses. HTTP method handling: Both support standard methods (GET, POST, etc.), but Route Handlers provide a cleaner API with exported functions per method. Middleware integration: Route Handlers automatically respect middleware and have access to the same runtime context, including cookies and headers. ```tsx // pages/api/users.ts import type { NextApiRequest, NextApiResponse } from 'next'; type ResponseData = { name: string; email: string; }; export default async function handler( req: NextApiRequest, res: NextApiResponse ) { if (req.method !== 'GET') { return res.status(405).json({ error: 'Method not allowed' }); } try { const users = await fetch('https://api.example.com/users').then(r => r.json()); res.status(200).json(users); } catch (error) { res.status(500).json({ error: 'Failed to fetch users' }); } } // Usage: GET /api/users // Limitations: // - No built-in caching // - Must manually handle method checks // - Only Node.js runtime // - No streaming ``` ```tsx // app/api/users/route.ts import { NextResponse } from 'next/server'; export async function GET(request: Request) { // Route Handlers get standard Request object, not NextApiRequest const { searchParams } = new URL(request.url); const limit = searchParams.get('limit') || '10'; const users = await fetch(`https://api.example.com/users?limit=${limit}`, { // Built-in caching with Next.js next: { revalidate: 3600, tags: ['users'] } }).then(r => r.json()); return NextResponse.json(users, { status: 200, headers: { 'Cache-Control': 'public, s-maxage=3600', }, }); } export async function POST(request: Request) { const body = await request.json(); // Validate and process const newUser = await createUser(body); // Revalidate cache // await revalidateTag('users'); return NextResponse.json(newUser, { status: 201 }); } // Usage: GET /api/users?limit=20 // POST /api/users with JSON body // Benefits: // - Automatic method routing (export per method) // - Built-in caching options // - Standard Request/Response objects // - Can run on Edge or Node.js ``` Route Handlers can stream responses using web streams, enabling real-time data delivery, server-sent events, and efficient large file transfers. This was impossible with API Routes, which had to send the complete response at once. You can now build endpoints that progressively send data, improving perceived performance for large datasets or enabling live updates without WebSockets. ```tsx // app/api/stream/route.ts // Simulate a slow data source async function* generateData() { for (let i = 0; i < 10; i++) { await new Promise(resolve => setTimeout(resolve, 1000)); yield `data: Chunk ${i} `; } } export async function GET() { const encoder = new TextEncoder(); const stream = new ReadableStream({ async start(controller) { for await (const chunk of generateData()) { controller.enqueue(encoder.encode(chunk)); } controller.close(); }, }); return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', }, }); } // This creates an SSE endpoint that clients can listen to for real-time updates ``` Route Handlers can run on the Edge Runtime, deploying your API endpoints to global edge locations for minimal latency. This is particularly valuable for personalization, geolocation-based responses, or any API that benefits from being close to users. You enable it with `export const runtime = 'edge'` in your route file. Edge Runtime has limitations (no Nod

What is the difference between API Routes (Pages Router) and Route Handlers (App Router)? What new capabilities do Route Handlers have?

Route Handlers replace API Routes with a more flexible, file-based system that supports streaming, Edge Runtime, CORS configuration, and direct access to Next.js caching, while running in both Node.js and Edge environments

What is the difference between API Routes (Pages Router) and Route Handlers (App Router)? What new capabilities do Route Handlers have?

Route Handlers replace API Routes with a more flexible, file-based system that supports streaming, Edge Runtime, CORS configuration, and direct access to Next.js caching, while running in both Node.js and Edge environments

Scenario Questions

Follow-up Questions