API в Next.js: маршруты, примеры и лучшие практики

08 Apr 2026 • 6 min read • Веб-разработка • Обновлено 08 Apr 2026

Кратко: В этой статье показано, как создавать серверные API-маршруты внутри проекта Next.js, обрабатывать запросы GET и POST и потреблять их с фронтенда. Приведены практические советы, сценарии, альтернативы и чек-листы для безопасной и устойчивой реализации.

Женщина пишет «use apis» на белой доске

Исчезли времена, когда для сайта нужно было заводить отдельный бэкенд. С файловой маршрутизацией API в Next.js вы можете писать серверную логику прямо в проекте Next.js и упростить разработку полнофункциональных приложений.

Next.js — это мета‑фреймворк для React с набором возможностей, которые упрощают создание production‑готовых веб‑приложений. Ниже показано, как создать REST API в Next.js и потреблять данные этого API на странице Next.js.

Что вы узнаете

Как создать проект Next.js и добавить API‑маршруты.
Как реализовать обработку GET и POST запросов.
Как с фронтенда вызывать свои маршруты и обновлять UI.
Лучшие практики безопасности и развертывания.

Создание проекта Next.js с помощью create-next-app

Вы можете создать новый проект Next.js с помощью инструмента CLI create-next-app. Он установит необходимые пакеты и файлы для старта.

Запустите эту команду в терминале, чтобы создать папку проекта api-routes. В процессе может понадобиться установить create-next-app:

npx create-next-app api-routes

Когда команда завершит работу, откройте папку api-routes, чтобы начать создавать маршруты API.

Маршрутизация API в Next.js

API‑маршруты выполняются на сервере и полезны для сохранения данных в базе, обращения к сторонним API без проблем с CORS и реализации любой серверной логики.

В Next.js файлы маршрутов API нужно размещать в папке /pages/api. Для каждого файла в этой папке Next.js генерирует конечную точку. Если вы добавите user.js в /pages/api, Next.js создаст endpoint по адресу http://localhost:3000/api/user.

Базовый API‑маршрут в Next.js имеет такой синтаксис:

export default function handler(req, res) {  
  res.status(200).json({ name: 'John Doe' })  
}

Не забудьте экспортировать handler — это обязательный контракт для работы маршрута.

Создание маршрутов API

Добавьте файл todo.js в папку /pages/api, чтобы создать маршрут для работы со списком задач (todos).

Мокирование «базы данных» задач

Для примера реализуем GET‑эндпоинт, возвращающий список задач. В обучающих целях здесь используется массив объектов вместо реальной базы данных — вы всегда можете подключить MongoDB, MySQL или другую СУБД.

Создайте массив todos в корне приложения (файл todo.js) и добавьте следующие данные:

export const todos = [  
  {  
    id: 1,  
    todo: "Do something nice for someone I care about",  
    completed: true,  
    userId: 26,  
  },  
  {  
    id: 2,  
    todo: "Memorize the fifty states and their capitals",  
    completed: false,  
    userId: 48,  
  },  
  // other todos  
];

Эти данные взяты с DummyJSON — сервиса с мок‑данными. Вы можете использовать точный ответ из их todos‑эндпоинта для тестов.

Далее создайте маршрут /pages/api/todos.js и добавьте обработчик:

import { todos } from "../../todo";  
   
export function handler(req, res) {  
  const { method } = req;  
   
  switch (method) {  
    case "GET":  
      res.status(200).json(todos);  
      break;  
    case "POST":  
      const { todo, completed } = req.body;  
      todos.push({  
        id: todos.length + 1,  
        todo,  
        completed,  
      });  
      res.status(200).json(todos);  
      break;  
    default:  
      res.setHeader("Allow", ["GET", "POST"]);  
      res.status(405).end(`Method ${method} Not Allowed`);  
      break;  
  }  
}

Этот маршрут обрабатывает GET и POST: GET возвращает все задачи, POST добавляет новую задачу в массив. Для прочих методов возвращается ошибка 405.

Потребление API на фронтенде

Вы создали API, возвращающее JSON со списком todos. Теперь напишем функцию fetchTodos, которая получает данные с конечной точки. В примере используется fetch, но можно применять и Axios.

Пример компонента, который получает задачи по клику и отображает их:

import Head from "next/head";  
import { useState } from "react";   
   
export default function Home() {  
  const [todos, settodos] = useState([]);  
   
  const fetchTodos = async () => {  
    const response = await fetch("/api/todos");  
    const data = await response.json();  
    settodos(data);  
  };  
   
  return (  
      
        
        Create Next App  
          
          
        
        
        Get todos  
          
          {todos.map((todo) => {  
            return (  
                
                {todo.todo}:{todo.completed}.  
                
            );  
          })}

  
  );  
}

Список отобразит задачи после выполнения fetch.

Пример сохранения (POST)

Для POST создайте функцию saveTodo, которая делает fetch с методом POST и телом JSON. Ответ API — обновлённый список задач, который сохраняется в состоянии todos:

const saveTodo = async () => {  
    const response = await fetch("/api/todos", {  
        method: "POST",  
        body: JSON.stringify(newTodo),  
        headers: {  
            "Content-Type": "application/json",  
        },  
    });  
   
    const data = await response.json();  
    settodos(data);  
};

И форма для ввода нового todo:

import Head from "next/head";  
import { useReducer, useState } from "react";  
import styles from "../styles/Home.module.css";  
   
export default function Home() {  
  const [todos, settodos] = useState([]);  
   
  const [newTodo, setnewTodo] = useState({  
    todo: "",  
    completed: false,  
  });  
   
  const fetchTodos = async () => {  
    // fetchTodos  
  };  
  
  const saveTodo = async (e) => {  
    const response = await fetch("/api/todos", {  
      method: "POST",  
      body: JSON.stringify(newTodo),  
      headers: {  
        "Content-Type": "application/json",  
      },  
    });  
   
    const data = await response.json();  
    settodos(data);  
  };  
   
  const handleChange = (e) => {  
    setnewTodo({  
      todo: e.target.value,  
    });  
  };  
   
  const handleSubmit = (e) => {  
    e.preventDefault();  
    saveTodo();  
    setnewTodo({  
      todo: '',  
    });  
  };  
   
  return (  
      
        
        Create Next App  
          
          
        
        
// Fetches the todo items when clicked  
        Get todos  
   
// Saves a new todo item when submitted  
          
            
          
          
          {// list todo items}

  
  );  
}

Обработчик добавляет новую задачу при каждом submit и обновляет состояние todos на основе ответа API.

Лучшие практики

Разделяйте ответственность: маршруты API должны выполнять только серверные задачи (валидация, доступ к БД, аутентификация). Логика отображения остаётся в компонентах React.
Валидация входных данных на сервере: всегда проверяйте тело запроса и типы полей.
Ограничение методов и корректные коды ответа: 405 для неподдерживаемых методов, 400 для неверных данных, 500 для серверных ошибок.
Используйте environment‑переменные для секретов и строк подключения.
Кеширование и сжатие там, где это уместно.

Важно: для production не храните данные в памяти процесса (как массив в файле). Это подходит только для локальной разработки и демонстраций.

Когда маршруты API Next.js не подходят

Нужна масштабируемая отдельная сервисная архитектура с собственным циклом деплоймента — предпочтительнее выделенный бэкенд или микросервис.
Требуется долгоживущий фон‑процесс или очередь задач — используйте отдельные worker‑процессы или managed‑сервисы.
Нужна совместимость с архитектурами, где frontend и backend деплоятся независимо с разными командами — тогда отдельный API удобнее.

Альтернативные подходы

Сервер без Next.js: Express, Fastify, NestJS.
Отдельные серверless‑функции (AWS Lambda, Vercel Functions) — подходят для автономных endpoint’ов.
BFF (Backend for Frontend): отдельный слой между UI и микросервисами.

Мини‑методология: шаги для быстрой реализации API в проекте Next.js

Инициализация проекта: npx create-next-app .
Создать структуру: /pages/api/.js.
Продумать модели и валидацию данных.
Реализовать обработчики методов (GET/POST/PUT/DELETE по необходимости).
Локально протестировать через curl или Postman.
Добавить логи и обработку ошибок.
Перевести хранение данных на реальную БД перед деплоем.
Обновить окружение и настроить CI/CD.

Чек-листы по ролям

Разработчик:
- Реализовал валидацию и тесты для эндпоинта.
- Добавил обработку ошибок и возвращаемые статусы.
- Не хранит секреты в репозитории.
Ревьювер/QA:
- Протестировал GET/POST и сценарии ошибочных запросов.
- Проверил заголовки CORS и авторизации.
DevOps:
- Настроил переменные окружения.
- Обеспечил резервирование и бэкапы БД.

Безопасность и приватность

Всегда валидируйте и нормализуйте входные данные.
Ограничьте размер тел запросов и избегайте выполнения произвольного кода на основе входа.
Храните секреты в менеджере секретов или переменных окружения.
Для персональных данных соблюдайте требования локального законодательства о защите данных (например, GDPR в ЕС): документируйте цели обработки, поддерживайте право удаления и доступа.

Критерии приёмки

GET /api/todos возвращает 200 и массив задач в формате JSON.
POST /api/todos с корректным JSON добавляет задачу и возвращает обновлённый массив.
Для неподдерживаемых методов возвращается 405 и заголовок Allow.
Ошибки валидации приводят к 400 с читаемым сообщением.

Факты и подсказки

Путь для API: /pages/api — каждый файл превращается в endpoint.
По умолчанию Next.js запускается на порту 3000 при локальном старте.
Типичные методы: GET, POST, PUT, DELETE.

Краткое резюме

API‑маршруты Next.js позволяют быстро добавить серверную логику в тот же проект, что и фронтенд. Для небольших или средних приложений это удобное и быстрое решение. Для production‑нагрузок и сложной серверной логики стоит продумать отдельную архитектуру и хранение данных вне памяти процесса.

Ключевые рекомендации: валидируйте вход, не храните данные в памяти для production, используйте environment‑переменные и планируйте развертывание с учётом масштабирования.