Обработчики маршрутов: Route Handlers

Создаём собственные API-эндпоинты прямо в проекте через файлы route.js.

Route Handler — файл route.ts, экспортирующий функции с именами HTTP-методов (GET, POST и т. д.); он создаёт настоящий API-эндпоинт по своему пути в папке app/.

Когда нужен API

Серверные компоненты и Server Actions покрывают большинство случаев. Но иногда нужен именно HTTP-эндпоинт: вебхук от платёжной системы, JSON для мобильного приложения, эндпоинт для стороннего сервиса. Для этого есть Route Handlers.

Создаём эндпоинт

Файл app/api/hello/route.ts станет доступен по адресу /api/hello. Экспортируем функцию с именем метода:

// app/api/hello/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Привет из API" });
}

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

Имя файла обязательно route (не page) — это и есть признак API-маршрута. В одной папке нельзя держать одновременно page и route.

Ответ эндпоинта

Эндпоинт GET /api/hello вернёт обычный JSON:

{ "message": "Привет из API" }

Динамические эндпоинты

Route Handlers тоже поддерживают динамические сегменты. Файл app/api/users/[id]/route.ts примет params.id — ровно как страницы:

Файл	URL	Методы
`app/api/posts/route.ts`	/api/posts	GET, POST
`app/api/posts/[id]/route.ts`	/api/posts/5	GET, PUT, DELETE

Когда что выбирать

Простое правило: для отрисовки страницы данные грузите в серверном компоненте; для изменения данных из формы — Server Action; полноценный Route Handler заводите, когда эндпоинт нужен внешнему потребителю (мобайл, вебхук, сторонний сервис).

Итог

Файл route.ts экспортирует функции GET/POST/… и создаёт API-эндпоинт.
NextResponse.json(...) — удобный способ вернуть JSON.
Route Handlers нужны для внешних потребителей; внутри приложения чаще хватает компонентов и действий.