Route Handlers: Your Next.js App's API Endpoints

Why it exists

Web applications need more than just user-facing pages. They need endpoints to handle data mutations, serve dynamic information, and integrate with other services. Route Handlers provide a file-based convention to create these API endpoints directly within the Next.js App Router, removing the need for a separate backend server for many use cases.

The mental model

A Route Handler is like a serverless function scoped to a specific URL in your app. You create a route.js file inside a folder (e.g., app/api/users/route.js), and that file becomes an API endpoint at /api/users. It doesn't render HTML; it takes a web Request and returns a Response.

How it works

Within a route.js file, you export async functions named after the HTTP methods they handle: GET, POST, PUT, DELETE, etc. When a request with a matching method hits the route's URL, Next.js executes the corresponding function. These functions receive a NextRequest object (an extended version of the standard Request API) and must return a NextResponse object, allowing you to easily send JSON data, set status codes, and manage headers.

When to use it

Use Route Handlers whenever you need to expose an API endpoint from your Next.js application. This is ideal for three main scenarios: first, providing data to your client-side components (e.g., a search endpoint); second, handling form submissions that need to write to a database; and third, creating webhook endpoints for third-party services like Stripe or GitHub to call.

When not to use it

Do not use Route Handlers to render HTML or React components. That is the job of page.js files. If your goal is to return a UI, you are using the wrong tool. For extremely complex or high-traffic APIs, a dedicated, separate backend service might still be a better choice for architectural separation and independent scaling.

One canonical example

To create an endpoint at /api/items that returns a JSON array, you would create the file app/api/items/route.js. Inside this file, you would export an async function named GET. This function can fetch data and return it using the NextResponse.json() helper. For example: import { NextResponse } from 'next/server'; export async function GET(request) { const items = [{ id: 1, name: 'Item A' }]; return NextResponse.json({ items }); }