Route Handlers (API Routes)

Build API endpoints directly inside your Next.js project using route.ts files.

What Is a Route Handler?

A Route Handler is Next.js's built-in way to define a traditional API endpoint. A file named route.ts (or .js) inside app/ exports functions named after HTTP methods, and Next.js wires each one up to requests using that method at that route's path.

app/api/posts/route.ts   →  /api/posts (GET, POST, etc.)

Handling Different HTTP Methods

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

export async function GET() {
  const posts = await db.post.findMany();
  return NextResponse.json(posts);
}

export async function POST(request) {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

A single route.ts can export GET, POST, PUT, PATCH, and DELETE — Next.js calls whichever one matches the incoming request's method, and returns a 405 automatically for methods you haven't defined.

Reading the Request

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const category = searchParams.get('category');

  const posts = await db.post.findMany({ where: { category } });
  return NextResponse.json(posts);
}

Dynamic API Routes

Route Handlers support the same dynamic segment conventions as pages — a folder named [id] captures a URL parameter, passed as the second argument.

// app/api/posts/[id]/route.ts
export async function GET(request, { params }) {
  const post = await db.post.findUnique({ where: { id: params.id } });
  if (!post) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }
  return NextResponse.json(post);
}

When to Use a Route Handler vs a Server Action

Use a Route Handler when...	Use a Server Action when...
You need a public API consumed by external clients (mobile apps, webhooks)	The mutation is triggered from your own app's forms or buttons
You need a specific HTTP method or response format	You want the simplicity of calling a server function directly from a component
You're receiving a webhook from a third-party service	You're handling a typical create/update/delete from your own UI

Common Beginner Mistakes

Naming the file api.ts instead of route.ts

Next.js specifically looks for the file name route (with .ts, .js, .tsx), regardless of the folder it lives in.

Putting a route.ts and a page.tsx in the same folder

A folder can't serve both a page and a Route Handler at the same segment — separate them into different folders (e.g. app/posts/page.tsx vs app/api/posts/route.ts).

FAQs

Are Route Handlers cached like page fetches?

GET Route Handlers can be cached in some configurations, but by default they behave dynamically — check the caching lesson's coverage of route segment config if you need to control this.

Can a Route Handler use middleware?

Yes — middleware runs before Route Handlers too, since it operates at the request level, covered in an upcoming lesson.

Summary

Route Handlers give you a full backend API inside your Next.js project, using familiar HTTP method names. Next, you'll learn Server Actions — a more direct way to run server code from your own UI without a separate endpoint.

Next Lesson →