API Routes и Route Handlers: что это и где их создавать
На этой странице
API-маршрут — серверный обработчик HTTP-запросов. Вместо страницы он возвращает JSON, файл или другой ответ. В App Router это Route Handlers — файлы route.ts; в Pages Router — API Routes в pages/api. Путь файла определяет URL.
Вопрос
Зачем нужны API-маршруты, как они устроены в Next.js и в какую папку положить обработчик, чтобы получить нужный адрес?
Основная идея
API удобно представлять как адрес для обмена данными: GET /api/books получает список книг, POST /api/books создает запись.
Route Handlers используют стандартные объекты Request и Response. Обработчик выполняется на сервере. К нему может обратиться браузер, мобильное приложение или внешний сервис. Это удобно для публичного API, вебхуков и случаев, когда нужны собственные HTTP-статусы и заголовки.
Где создавать
В App Router папки образуют части URL, а route.ts объявляет обработчик. Папка api — удобное соглашение, а не обязательное имя. В Pages Router папка pages/api имеет специальное назначение: ее файлы обрабатывают запросы, а не становятся страницами.
| Файл | URL | Механизм |
|---|---|---|
app/api/books/route.ts | /api/books | App Router |
app/api/books/[id]/route.ts | /api/books/42 | Динамический Route Handler |
pages/api/books.ts | /api/books | Pages Router |
Если проект использует src, каталоги находятся в src/app или src/pages.
Пример: список книг
// app/api/books/route.ts
export async function GET() {
return Response.json([
{ id: 1, title: "Изучаем JavaScript" },
{ id: 2, title: "Первые шаги с React" },
]);
}Next.js связывает экспорт функции с HTTP-методом; можно объявить POST, PATCH, DELETE и другие методы. Из браузерного обработчика:
async function loadBooks() {
const response = await fetch("/api/books");
if (!response.ok) throw new Error("Не удалось получить книги");
return response.json();
}Пример: книга по идентификатору
// app/api/books/[id]/route.ts
export async function GET(
_request: Request,
context: { params: Promise<{ id: string }> }
) {
const { id } = await context.params;
const books = [{ id: "1", title: "Изучаем Next.js" }];
const book = books.find(item => item.id === id);
if (!book) {
return Response.json({ error: "Книга не найдена" }, { status: 404 });
}
return Response.json(book);
}/api/books/1 вернет книгу, /api/books/99 — статус 404. В Next.js 16 params нужно ожидать через await.
Что важно помнить
- Серверное выполнение скрывает код обработчика, но не закрывает доступ к URL. Для приватных данных нужны проверка сессии, прав и входных данных.
- Server Component может вызвать функцию работы с базой напрямую — обращаться к собственному HTTP API ради загрузки необязательно. Для форм внутри приложения есть Server Actions.
route.tsиpage.tsxнельзя размещать на одном уровне для одного URL.- Не создавай два обработчика для одного адреса в
appиpagesодновременно. - GET-обработчики в современном Next.js по умолчанию не кэшируются.
Мини-шпаргалка
- App Router:
app/.../route.tsс экспортомGET,POST… - Pages Router:
pages/api/*. - URL = путь файла,
[id]— динамический сегмент. - Проверяй права и входные данные в каждом обработчике.