Next.js Route Handlers vs API Routes: When to Use Each (Practical Examples)

If you’re building a Next.js app, you’ll hit this question sooner than you think: next.js route handlers vs api routes — which one should you use?

The short answer is that both can work, but they’re not meant for the same kind of job. Route Handlers are the cleaner, newer way to build server endpoints in the App Router. API Routes are the older Pages Router approach that still matters in plenty of codebases. Pick the wrong one and you can make your app harder to maintain than it needs to be. Pick the right one and everything feels simpler.

I’ve seen teams overcomplicate this decision. They treat it like a religious debate. It isn’t. It’s just a practical choice about project structure, runtime needs, and how much of Next.js you’re actually using. And if you’re shipping a product fast, that choice matters a lot.

Route Handlers and API Routes: the real difference

At a high level, both let you create server-side endpoints in Next.js. You can use them to:

• fetch data
• handle form submissions
• process authentication callbacks
• accept webhook requests
• connect your frontend to databases or external services

But the implementation differs.

API Routes

API Routes live in the pages/api directory. They’ve been around for years and are tied to the Pages Router. A typical file might look like this:

// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'Hello from API Routes' })
}

They use the familiar Node.js-style req and res objects. If you’ve worked with Express, the pattern feels comfortable.

Route Handlers

Route Handlers live in the App Router under app/api/.../route.ts. They use standard Web APIs like Request and Response.

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: 'Hello from Route Handlers' })
}

That difference is bigger than it looks. Route Handlers fit better with the modern direction of Next.js, and in my opinion, they’re the better default for new projects.

Why Next.js changed direction

Next.js has been moving toward a more flexible app model. The App Router gives you nested layouts, server components, streaming, and a cleaner way to organize features. Route Handlers fit into that model naturally.

That doesn’t mean API Routes are obsolete. Far from it. Lots of production apps still use them, and some teams won’t need to touch them for a long time. But if you’re starting fresh, Route Handlers line up better with the rest of the framework.

Ask yourself this: do you want to build with the older routing model and keep one foot in the past, or do you want your project structure to match where Next.js is headed? I know which one I’d pick for a greenfield SaaS build.

A practical comparison

Here’s the version I’d give a product team that just wants to make the right call.

Feature	API Routes	Route Handlers
Router	Pages Router	App Router
File location	pages/api/*	app/api/*/route.ts
Request/response style	req, res	Web Request, Response
Best for	Legacy projects, simple endpoints, existing Pages Router apps	New App Router projects, modern server logic, cleaner endpoint organization
Middleware support	Yes	Yes
Streaming	Limited	Better fit
Edge runtime	Limited in older setups	Better support
Familiarity	Easier for Express-style developers	Better aligned with modern Web APIs

My take? If your team is already all-in on App Router, Route Handlers are the obvious choice. If you’ve got a mature Pages Router app and a pile of API Routes already working, don’t rewrite them just for the sake of it.

When API Routes still make sense

API Routes still earn their keep in a few situations.

1. You’re maintaining an existing Pages Router app

This is the most obvious case. If the app already uses pages/, API Routes keep things consistent. No need to add a mixed routing model unless you actually want to.

2. Your team knows the Pages Router well

Sometimes the best tool is the one your team can ship with confidently. If your developers already know API Routes, there’s no prize for forcing a migration too early.

3. You have simple server endpoints and no App Router plans

If the product is stable and the endpoints are straightforward, API Routes are perfectly fine. A webhook receiver, a contact form endpoint, a newsletter signup handler — these don’t need to be fancy.

Here’s a simple example:

// pages/api/contact.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }

  const { name, email, message } = req.body

  // save to database or send email
  return res.status(200).json({ success: true })
}

It works. It’s readable. No drama.

When Route Handlers are the better choice

Route Handlers shine when you’re building with the App Router.

1. You’re starting a new Next.js app

This is the strongest reason to use Route Handlers. They fit the newer architecture, and that matters for long-term maintainability.

2. You want a web-standard API style

Route Handlers use the same Request and Response objects you’d see in browser or edge runtimes. That makes the code feel less framework-specific. Personally, I like this. It reduces the mental overhead when switching between frontend and backend code.

3. You need better support for modern runtime patterns

Route Handlers work well with edge-friendly approaches and newer Next.js features. That can be useful for faster responses, geo-distributed logic, or lightweight server tasks.

Here’s a Route Handler example:

// app/api/contact/route.ts
export async function POST(request: Request) {
  const body = await request.json()
  const { name, email, message } = body

  // save to database or send email
  return Response.json({ success: true })
}

Cleaner, right? There’s less framework noise around the request lifecycle.

Authentication, forms, and webhooks: where the difference matters

A lot of teams compare next.js route handlers vs api routes in the abstract, but the real answer shows up in day-to-day features.

Authentication callbacks

If you’re handling OAuth callbacks from providers like Google or GitHub, either option can work. But Route Handlers often feel more natural in new apps using App Router. You can keep the auth flow close to the rest of your server logic.

Contact forms and lead capture

For a marketing site or startup landing page, API Routes are still common, especially if the rest of the site uses Pages Router. But if the project is App Router-based, Route Handlers are usually the cleaner fit.

Webhooks

Webhooks are a great example because they’re all about raw request handling. Stripe, GitHub, and Slack webhooks often need precise header reading and signature verification.

Route Handlers make this pattern feel modern and direct:

// app/api/webhooks/stripe/route.ts
export async function POST(request: Request) {
  const payload = await request.text()
  const signature = request.headers.get('stripe-signature')

  if (!signature) {
    return new Response('Missing signature', { status: 400 })
  }

  // verify signature and process event
  return Response.json({ received: true })
}

That said, if you already have a solid API Route webhook pipeline, there’s no reason to rip it out.

Performance and runtime considerations

People love to ask which one is faster. The honest answer is that speed usually depends more on what your code does than whether you picked Route Handlers or API Routes.

Still, there are some meaningful differences.

Route Handlers can fit edge-oriented work better

Because they’re built around Web APIs, Route Handlers align well with edge runtimes and modern deployment patterns. That can help when you want low-latency responses or lightweight server logic close to users.

API Routes are more traditional Node-style handlers

That’s not bad. It just means they fit the classic server model better. If your code relies on Node-specific libraries or patterns, API Routes may feel easier, especially in an older app.

My opinion: don’t obsess over micro-performance here unless you know the runtime constraints. Most teams should optimize for clarity first.

If you’re making a product decision beyond just routing, Lunar Labs often helps teams sort out the architecture before they paint themselves into a corner. For broader technical planning, their strategy and discovery service is a smart place to start.

Migration: should you move from API Routes to Route Handlers?

Sometimes yes. Often no.

Here’s how I’d think about it.

Migrate if:

• you’re already moving to App Router
• you want one modern pattern across the codebase
• your team is comfortable with the Web API request model
• the endpoint logic is simple enough to port without risk

Keep API Routes if:

• the app is stable
• the current endpoints work well
• the team would lose time on a rewrite
• you have dependencies tied to the Pages Router setup

I’ve got a strong bias here: migrations should solve a problem, not create one. If the only reason you’re changing is because a blog post told you to, that’s not a great reason.

Real-world examples by product type

The best way to choose is to map the tool to the product.

SaaS dashboard

For a SaaS app built with the App Router, Route Handlers are usually the better fit. You may use them for:

• billing webhooks
• usage tracking
• team invites
• profile updates
• internal admin actions

That kind of product often benefits from a cleaner server boundary, especially if the frontend and backend logic live close together. If you’re building for SaaS, Lunar Labs’ Next.js development for SaaS page is worth a look.

Marketing site with a few forms

If the site still uses Pages Router, API Routes are totally fine. A contact form endpoint doesn’t need a full architectural makeover.

Startup MVP

For an MVP, choose the option that gets you to production with the least friction. That’s usually Route Handlers for a new App Router app, or API Routes for an older Pages Router base. The MVP stage is about momentum, not purity. If you’re still shaping the product, the idea of an MVP is covered well in Lunar Labs’ glossary.

Internal tools

Internal tools often prioritize speed of delivery and predictability. If your team already has API Routes in place, keep using them. If you’re starting fresh with the App Router, Route Handlers are the better long-term bet.

Common mistakes teams make

A few patterns come up again and again.

Mixing both without a reason

Yes, Next.js lets you use both. No, that doesn’t mean you should by default. Mixed patterns can confuse the team and make onboarding harder.

Choosing based on hype

Route Handlers are newer, but newer doesn’t automatically mean better for every project. I’d rather see a team use the older pattern well than adopt the new one badly.

Ignoring routing architecture

This part gets missed all the time. The question isn’t just next.js route handlers vs api routes. It’s really: what’s the routing foundation of the whole app? If you’re planning a broader rebuild, make sure the backend structure matches the frontend architecture.

Writing endpoint logic that should live elsewhere

Sometimes the route is the wrong place for business logic. If an endpoint starts growing into a mess, pull the domain logic into a service layer or utility module. The route should stay thin. That keeps things sane.

My rule of thumb

Here’s the simple version I use:

• New App Router project: use Route Handlers
• Existing Pages Router project: keep API Routes unless there’s a strong reason to move
• Need web-standard request handling: use Route Handlers
• Need to preserve legacy structure: use API Routes
• Building a small endpoint fast: either works, but pick the one that matches your app

That’s not glamorous, but it’s practical. And practical wins in shipping work.

What this means for teams building serious products

For startups and product teams, the routing decision can affect how quickly you iterate. A messy backend setup slows design changes, feature launches, and product experiments. A clean one gives your developers room to move.

That’s exactly where a studio like Lunar Labs tends to help. They don’t just build screens and endpoints. They think through the product structure, the user flow, and the technical choices that keep the whole thing manageable. If you’re planning a web app build, their web development services are a strong fit for teams that want thoughtful execution, not just code output.

Final verdict

If you want the shortest possible answer to next.js route handlers vs api routes, here it is:

• Use Route Handlers for new Next.js apps using the App Router.
• Use API Routes for existing Pages Router apps or when you need to preserve older structure.

That’s the real split.

Route Handlers are the modern default. API Routes are still useful. Neither is “bad.” They just serve different setups. The best choice is the one that fits your app today and won’t fight your team six months from now.

Ready to build the right Next.js foundation?

If you’re planning a new product, modernizing an existing SaaS, or trying to clean up a tangled Next.js codebase, Lunar Labs can help you make the right architectural calls before the first sprint turns into technical debt.

Explore their work, start a conversation, and build with a team that thinks about product, design, and engineering together.

Visit Lunar Labs to get started.