Урок 01

Что такое Route Handlers

Route Handlers — API-роуты в App Router. Создаются файлами route.ts внутри app/.

Базовый пример

app/api/hello/route.ts:

import { NextResponse } from 'next/server';

export async function GET() {
    return NextResponse.json({ message: 'Hello' });
}

URL: /api/hello.

Когда использовать

Webhooks — от внешних сервисов
Публичные API — для мобильных приложений
Внешние интеграции — OAuth, платежи
Streaming — SSE, AI-ответы
Файлы — загрузка, скачивание

Когда не использовать

Внутренние мутации — Server Actions проще
Загрузка данных в Server Components — прямой доступ к БД
Формы — Server Actions

Отличие от API Routes (Pages Router)

В Pages Router был pages/api/*.ts с export default function handler(req, res). В App Router — app/api/*/route.ts с экспортами GET, POST.

Методы

export async function GET(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function PATCH(request: Request) {}
export async function DELETE(request: Request) {}
export async function HEAD(request: Request) {}
export async function OPTIONS(request: Request) {}

Каждая функция — свой HTTP-метод. Если метод не экспортирован — 405.

Динамические сегменты

app/api/posts/[id]/route.ts

export async function GET(
    request: Request,
    { params }: { params: Promise<{ id: string }> }
) {
    const { id } = await params;
    return NextResponse.json({ id });
}

Catch-all

app/api/[...path]/route.ts

export async function GET(
    request: Request,
    { params }: { params: Promise<{ path: string[] }> }
) {
    const { path } = await params;
    return NextResponse.json({ path });
}

Response

// JSON
return NextResponse.json({ data });
return Response.json({ data });

// Статус
return NextResponse.json({ error: 'Not found' }, { status: 404 });

// Пустой
return new Response(null, { status: 204 });

// Текст
return new Response('Hello');

// Редирект
return NextResponse.redirect(new URL('/login', request.url));

Итоги

route.ts в app/api/
Экспорты GET, POST, PUT, PATCH, DELETE
Для внешних клиентов
Server Actions для внутренних мутаций
params — промис