Route Handlers (API Routes)

Server actions cover most internal mutations, but sometimes you genuinely need an HTTP endpoint — for webhooks, third-party callers, or non-React clients. Route handlers are that.

Where they live

Create a route.js file in any folder under app/ (instead of page.js). The folder's path becomes the URL.

app/api/hello/route.js   → GET/POST/etc to /api/hello
app/webhooks/stripe/route.js → /webhooks/stripe

Exporting HTTP methods

Export a function for each HTTP method you want to handle. They receive a Web Request and return a Web Response:

// app/api/hello/route.js
export async function GET() {
  return Response.json({ message: "Hello" });
}

export async function POST(request) {
  const body = await request.json();
  return Response.json({ echoed: body }, { status: 201 });
}

Reading query params and dynamic segments

// app/api/items/[id]/route.js
export async function GET(request, { params }) {
  const { id } = await params;
  const url = new URL(request.url);
  const fields = url.searchParams.get("fields");
  return Response.json({ id, fields });
}

Caching behavior

By default, GET route handlers are not cached in Next.js 16 — you opt in. The same dynamic/revalidate exports from lesson 12 work here too:

// app/api/posts/route.js
export const revalidate = 60;

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

POST, PUT, PATCH, DELETE are always dynamic — they perform side effects, so caching wouldn't make sense.

Route handler vs. server action

• Use a **server action** for internal form submissions and mutations from your own UI.
• Use a **route handler** for everything that needs a stable, public HTTP contract.
• Both run on the server. Both can hit your database. Pick the one that fits the caller.