Перейти к содержанию

Введение

Любой файл, находящийся в директории pages/api, привязывается к /api/* и считается конечной точкой (endpoint) API, а не страницей. Код интерфейса маршрутизации остается на сервере и не влияет на размер клиентской сборки.

Следующий пример роута pages/api/user.js возвращает статус-код 200 и данные в формате JSON:

export default function handler(req, res) {
  res.status(200).json({ name: 'Иван Петров' });
}

Функция handler принимает два параметра:

  • req — экземпляр http.IncomingMessage + несколько встроенных посредников
  • res — экземпляр http.ServerResponse + несколько вспомогательных функций

Для обработки различных методов можно использовать req.method:

export default function handler(req, res) {
  if (req.method === 'POST') {
    // работаем с POST-запросом
  } else {
    // работаем с другим запросом
  }
}

Случаи использования

В новом проекте весь API может быть построен с помощью интерфейса маршрутизации. Существующий API не требуется обновлять. Другие случаи:

  • маскировка URL внешнего сервиса
  • использование переменных среды окружения, хранящихся на сервере, для безопасного доступа к внешним сервисам

Особенности

  • интерфейс маршрутизации не определяет CORS-заголовки по умолчанию. Это делается с помощью посредников (см. ниже)
  • интерфейс маршрутизации не может использоваться вместе с next export

Что касается динамических сегментов в роутах интерфейса маршрутизации, то они подчиняются тем же правилам, что и динамические части роутов страниц.