re:re:actable
Урок 033 минуты чтения

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/booksApp Router
app/api/books/[id]/route.ts/api/books/42Динамический Route Handler
pages/api/books.ts/api/booksPages 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] — динамический сегмент.
  • Проверяй права и входные данные в каждом обработчике.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам