API маршрути (обробники маршрутів) у Next.js

Обробники маршрутів (які в маршрутизаторі сторінок називаються API маршрути) дозволяють створювати серверні API кінцеві точки безпосередньо в додатку Next.js. Вони визначаються у файлах route.ts, які знаходяться в директорії app.

Основний приклад

tsx

// app/api/problems/route.ts
import { NextResponse } from 'next/server'
import { db } from '@/lib/db'

export async function GET() {
  const problems = await db.problem.findMany()
  return NextResponse.json(problems)
}

export async function POST(request: Request) {
  const body = await request.json()

  const problem = await db.problem.create({
    data: body
  })

  return NextResponse.json(problem, { status: 201 })
}

Кожен експортований метод (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) обробляє відповідний HTTP запит.

Динамічні обробники маршрутів

tsx

// app/api/problems/[id]/route.ts
import { NextResponse } from 'next/server'
import { db } from '@/lib/db'

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const problem = await db.problem.findUnique({
    where: { id: params.id }
  })

  if (!problem) {
    return NextResponse.json(
      { error: 'Проблему не знайдено' },
      { status: 404 }
    )
  }

  return NextResponse.json(problem)
}

export async function DELETE(
  request: Request,
  { params }: { params: { id: string } }
) {
  await db.problem.delete({ where: { id: params.id } })
  return new Response(null, { status: 204 })
}

Робота з запитом

Обробники маршрутів використовують стандартний Web API Request:

tsx

// app/api/search/route.ts
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q')

  if (!query) {
    return NextResponse.json(
      { error: 'Параметр запиту обов\'язковий' },
      { status: 400 }
    )
  }

  const results = await db.problem.findMany({
    where: { name: { contains: query, mode: 'insensitive' } }
  })

  return NextResponse.json(results)
}

Читання заголовків і куків

tsx

import { cookies, headers } from 'next/headers'

export async function GET() {
  const cookieStore = cookies()
  const token = cookieStore.get('session')

  const headersList = headers()
  const userAgent = headersList.get('user-agent')

  return NextResponse.json({ token, userAgent })
}

Кешування

GET запити, які не читають запит, кешуються за замовчуванням:

tsx

// Кешований (статичний обробник маршруту)
export async function GET() {
  const data = await fetch('https://api.example.com/data')
  return NextResponse.json(data)
}

// Не кешується (читає запит)
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  // ...
}

Для явного контролю кешу:

tsx

export const dynamic = 'force-dynamic' // завжди динамічний
export const revalidate = 300          // перевіряти через 5 хвилин

Обробники маршрутів vs Серверні дії

	Обробники маршрутів	Серверні дії
Призначення	API кінцеві точки	Мутації UI
HTTP методи	GET, POST, PUT, DELETE...	Тільки POST
Викликаються з	Будь-якого клієнта (fetch, curl)	Тільки з компонентів
Прогресивне покращення	Ні	Так (форми)

Коли використовувати що:

Використовуйте Серверні дії для мутацій даних з інтерфейсу (форми, кнопки). Використовуйте Обробники маршрутів для публічних API, вебхуків, інтеграцій з зовнішніми сервісами та випадків, коли потрібні специфічні HTTP методи.

Корисні ресурси

nextjs.org/docs — Обробники маршрутів
route.ts API Reference

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Дочитали статтю?

Практика завдань

API маршрути (обробники маршрутів) у Next.js

#Основний приклад

#Динамічні обробники маршрутів

#Робота з запитом

#Читання заголовків і куків

#Кешування

#Обробники маршрутів vs Серверні дії

#Корисні ресурси