What are Route Handlers in Next.js and how do they differ from Pages API routes?

Q: What are Route Handlers in Next.js and how do they differ from Pages API routes?

**Target Audience:** Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. **Difficulty:** Medium > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the **Verified** section, against real output from a build or a running server; each Verified block says which version it ran on. ## 1. Why This Even Matters — A Story First A Pages API route is a receptionist who answers every call to one number and then asks "what do you want?" before deciding what to do. A Route Handler is an office with separate doors marked GET, POST and DELETE: you walk through the door for what you want, and a door that is not there is simply a locked wall with a 405 sign. ## 2. The Core Idea 📌 **Interview term: Route Handler** — an App Router file named route.ts

The problem

Question presented to candidate: "You are moving /pages/api endpoints to the App Router. What are Route Handlers, how is the code different, and what do you need to watch for?"

What a strong answer should cover:

A Route Handler is a route.ts file in app/ that exports functions named after HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS).
It uses the Web standard Request and Response (plus NextRequest and NextResponse helpers), not Node-style req and res.
Unexported methods return 405 automatically; dynamic segments arrive as an awaited params Promise in the second argument.
GET handlers are dynamic by default since Next.js 15; without Cache Components you opt into static output with export const dynamic = 'force-static'. With Cache Components (the create-next-app default in 16.4) that export is a build error: a GET is prerendered when it reads no request or uncached data, and 'use cache' caches the rest.
Pages API routes still work side by side; there is one default-exported handler(req, res) per file with a method switch.

Clarifying questions expected:

"Do any endpoints rely on Node-specific res methods or body parser config?" — they need rewriting.
"Should any GET endpoint be static?" — it now needs an explicit opt-in.

Code / implementation expected: Yes — the same endpoint in both styles.

nextjs
route-handlers
api
app-router

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. Difficulty: Medium

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the Verified section, against real output from a build or a running server; each Verified block says which version it ran on.

1. Why This Even Matters — A Story First

A Pages API route is a receptionist who answers every call to one number and then asks "what do you want?" before deciding what to do. A Route Handler is an office with separate doors marked GET, POST and DELETE: you walk through the door for what you want, and a door that is not there is simply a locked wall with a 405

The solution is hidden so you can try first

5 min read · 8 sections

Read the code

A Pages API route and its Route Handler version

// pages/api/items/[id].ts  (Pages Router)
import type { NextApiRequest, NextApiResponse } from "next";
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === "GET") return res.status(200).json(await getItem(String(req.query.id)));
  if (req.method === "DELETE") { await deleteItem(String(req.query.id)); return res.status(204).end(); }
  res.setHeader("Allow", "GET, DELETE").status(405).end();
}

// app/api/items/[id]/route.ts  (App Router)
export async function GET(_req: Request, ctx: { params: Promise<{ id: string }> }) {
  const { id } = await ctx.params;
  return Response.json(await getItem(id));
}
export async function DELETE(_req: Request, ctx: { params: Promise<{ id: string }> }) {
  const { id } = await ctx.params;
  await deleteItem(id);
  return new Response(null, { status: 204 });
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.