How to Use API Routes in Next.js for Backend Functionality (2025 Guide)

How to Use API Routes in Next.js for Backend Functionality

Building a modern web app often means juggling two codebases: one for the UI and another for the server. Next.js collapses that split by letting you write backend logic right inside your project. Depending on whether you’re using the Pages Router or the newer App Router, you’ll reach for API Routes or Route Handlers. This post walks through both approaches, highlights real-world patterns, and shares best practices for 2025 and beyond.

1. Why put your backend in Next.js?

• Backend-for-Frontend (BFF): create a thin API layer that lives next to the components that consume it — great for GraphQL wrappers, auth callbacks, or any logic that shouldn’t run in the browser. nextjs.org

• Zero-config serverless: on Vercel (and most hosts) every API file is compiled to a serverless or edge function automatically.

• Shared types & utilities: import the same validation schema or lib/db.ts from pages and server code alike.

2. API Routes in the Pages Router (/pages/api/*)

2.1 Basic example

// file: 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!' });
}

Every file in pages/api maps to /api/* and runs server-side only, never increasing the client bundle size. nextjs.org

2.2 Handling multiple HTTP verbs

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  switch (req.method) {
    case 'GET':
      return res.json({ posts: [] });
    case 'POST':
      // create a new post
      return res.status(201).end();
    default:
      res.setHeader('Allow', ['GET', 'POST']);
      return res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

2.3 Dynamic routes & parameters

pages/api/posts/[id].ts handles /api/posts/:id. Inside, access req.query.id.

2.4 Edge Runtime (optional)

Add an exported config block to move this route to the edge:

export const config = { runtime: 'edge' };

Edge routes start faster and sit closer to users, but lack full Node APIs. giovannibenussi.comnextjs.org

3. Route Handlers in the App Router (/app/api/route.ts)

Since Next.js 13/14, the App Router ships with Route Handlers — a lighter, Web-standard way to build endpoints. They live in the app directory and mirror the file-based routing you use for pages. nextjs.orgnextjs.org

3.1 Minimal handler

// file: app/api/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ message: 'Hello from Route Handlers!' });
}

Export a function whose name matches the HTTP verb (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD). The first parameter is a standard Request object; return a Response or NextResponse.

3.2 Streaming & Edge by default

Route Handlers work in both Node and Edge runtimes and support streaming responses out of the box. You can opt-in to Edge explicitly:

export const runtime = 'edge';          // runs on the Edge
export const dynamic = 'force-dynamic'; // disable static caching

Edge/Node parity and streaming support are part of what makes Route Handlers compelling. nextjs.orgrunebook.dev

3.3 Nested & dynamic segments

Place a route.ts in any nested folder

app/api/posts/[id]/route.ts   →  /api/posts/:id

3.4 Working with Server Actions

Because both Server Actions and Route Handlers live on the server, you can call one from the other (or retire simple handlers in favor of directly using actions). stackoverflow.com

4. Choosing between the two

If you start a brand-new Next.js 14 project, stick with Route Handlers. They’re lighter, Web-standard, and future-proof.

5. Best practices (works for both)

1. Validate inputs – plug in [Zod] or joi to parse req.body / await request.json().

2. Type safety – co-locate shared TypeScript types (e.g., Post) in types.ts and import on both sides.

3. Auth & sessions – use NextAuth.js or your provider’s JWT library; remember handlers run server-side only.

4. Error handling – return consistent JSON {error: '...'} with appropriate status codes.

5. Rate limiting & CORS – apply Middleware or libraries like @vercel/edge-config.

6. Keep them small – if business logic grows, graduate to a dedicated service or tRPC / GraphQL layer. Lee Robinson’s February 2025 guide echoes this advice. nextjs.org

6. Deployment & environment variables

• Vercel: each handler becomes a serverless or edge function automatically; logs appear in the dashboard.

• Self-hosting / Docker: run next start, and Next.js spins up an HTTP server that executes your handlers.

• Env vars: create .env.local and access them in handlers with process.env.MY_SECRET (API Routes) or process.env / NextResponse.json() (Route Handlers). The variables are never bundled to the client.

7. Conclusion

API Routes and Route Handlers let you blur the line between frontend and backend, speeding up full-stack development without spinning up a separate server. If you’re on the Pages Router, API Routes remain rock-solid. If you’re on the App Router — or starting fresh in 2025 — lean into Route Handlers for a thinner, faster layer that speaks the Fetch API and runs anywhere, even at the edge.

Happy building — and may your /api always return 200 OK! 🎉

Frequently Asked Questions (FAQ)

(Add this section at the end of your post to capture common doubts readers have after trying Next.js API Routes and Route Handlers.)