Как сделать HTTP API с Route Handlers
На этой странице
Route Handler преобразует HTTP-запрос в серверную операцию и возвращает статус, заголовки и тело ответа. Он может использовать тот же DAL, что и Server Actions.
Вопрос
Как предоставить чтение, создание, изменение и удаление задач через HTTP?
Основная идея
Сначала нужны DAL, сессии и схемы из предыдущих тем. Здесь API использует cookie-сессию и предназначен для браузера того же сайта. Для изменяющих запросов проверяем Origin: это часть защиты от CSRF, а не проверка личности.
Пример: общий HTTP-слой
// lib/http.ts
import "server-only";
import { ZodError } from "zod";
import { AppError } from "./errors";
export function assertMutationRequest(request: Request) {
const base = process.env.BETTER_AUTH_URL;
if (!base) throw new Error("Не задан BETTER_AUTH_URL");
if (request.headers.get("origin") !== new URL(base).origin) {
throw new AppError(403, "Недопустимый источник запроса");
}
}
export function assertJson(request: Request) {
const type = request.headers.get("content-type")?.split(";")[0].trim();
if (type !== "application/json") throw new AppError(415, "Нужен application/json");
}
export function apiError(error: unknown) {
if (error instanceof AppError) return Response.json({ error: error.message }, { status: error.status });
if (error instanceof ZodError) return Response.json({ error: "Неверные поля" }, { status: 422 });
if (error instanceof SyntaxError) return Response.json({ error: "Некорректный JSON" }, { status: 400 });
console.error("Ошибка API задач");
return Response.json({ error: "Внутренняя ошибка" }, { status: 500 });
}// app/api/tasks/route.ts
import { revalidatePath } from "next/cache";
import { listTasks, createTask } from "@/lib/tasks";
import { apiError, assertJson, assertMutationRequest } from "@/lib/http";
export const runtime = "nodejs";
export async function GET() {
try {
return Response.json(await listTasks(), { headers: { "Cache-Control": "private, no-store" } });
} catch (error) { return apiError(error); }
}
export async function POST(request: Request) {
try {
assertMutationRequest(request);
assertJson(request);
const task = await createTask(await request.json());
revalidatePath("/tasks");
return Response.json(task, { status: 201 });
} catch (error) { return apiError(error); }
}// app/api/tasks/[id]/route.ts
import { revalidatePath } from "next/cache";
import { updateTask, deleteTask } from "@/lib/tasks";
import { apiError, assertJson, assertMutationRequest } from "@/lib/http";
export const runtime = "nodejs";
type Context = { params: Promise<{ id: string }> };
export async function PATCH(request: Request, context: Context) {
try {
assertMutationRequest(request);
assertJson(request);
const { id } = await context.params;
const task = await updateTask(id, await request.json());
revalidatePath("/tasks");
return Response.json(task);
} catch (error) { return apiError(error); }
}
export async function DELETE(request: Request, context: Context) {
try {
assertMutationRequest(request);
const { id } = await context.params;
await deleteTask(id);
revalidatePath("/tasks");
return new Response(null, { status: 204 });
} catch (error) { return apiError(error); }
}Что важно помнить
Ответ 201 означает создание, 204 — успешное удаление без тела. Без сессии DAL вернет 401, чужая или отсутствующая задача даст 404. Клиент после 204 не должен вызывать response.json().
При вызове из браузера одного домена cookie передаются автоматически. Внешнему клиенту нужны отдельно спроектированные авторизация и правила доступа; снятие проверки Origin не превращает этот пример в безопасный публичный API. Размер тела, частоту запросов и таймауты ограничивают на уровне приложения и инфраструктуры.
revalidatePath не рассылает обновление всем открытым вкладкам. После клиентского fetch интерфейс обновляют состоянием, повторным запросом или router.refresh().
Мини-шпаргалка
- GET читает, POST создает, PATCH изменяет, DELETE удаляет.
- Статус и формат ответа входят в контракт API.
- Сессия, валидация и владелец проверяются на сервере.
- Actions и API используют один DAL.