Next.js: Fullstack dalam Satu Proyek · 6/9

Route Handler: membangun HTTP API

Kapan kamu butuh endpoint sungguhan alih-alih action, dan cara menulisnya dengan benar.

Baca 25 menit

Setelah pelajaran ini kamu bisa

Menulis Route Handler untuk setiap method HTTP
Menyebutkan kapan kamu membutuhkannya alih-alih Server Action
Mengembalikan status code dan JSON yang benar
Menjelaskan default caching untuk GET

Route Handler adalah endpoint HTTP sungguhan. Kamu menulis route.ts alih-alih page.tsx, dan meng-export function yang dinamai sesuai setiap method yang kamu dukung.

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

export async function GET(request: Request, { params }: RouteContext<"/api/venues/[id]">) {
  const { id } = await params;                 // a Promise, like page params

  const venue = await getVenue(Number(id));
  if (!venue) {
    return Response.json({ error: "Not found" }, { status: 404 });
  }
  return Response.json(venue);
}

export async function DELETE(request: Request, { params }: RouteContext<"/api/venues/[id]">) {
  // Authorise here too. A Route Handler is even more obviously public.
  const user = await getSessionUser();
  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });

  const { id } = await params;
  const venue = await getVenue(Number(id));
  if (!venue) return Response.json({ error: "Not found" }, { status: 404 });
  if (venue.ownerId !== user.id) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }

  await deleteVenue(venue.id);
  return new Response(null, { status: 204 });  // success, no body
}

Response.json() adalah standar web — tidak perlu helper framework. RouteContext<"..."> memberi type pada params dari path-nya, seperti PageProps.

Action atau handler?

Pakai	Saat
Server Action	Form atau tombol milikmu sendiri, di aplikasimu sendiri
Route Handler	Aplikasi mobile atau pihak ketiga perlu memanggilnya
Route Handler	Webhook dari Stripe, GitHub, gateway pembayaran
Route Handler	Kamu harus mengembalikan sesuatu yang bukan halaman: gambar, CSV, feed RSS
Route Handler	Kamu butuh URL, method, atau status code yang spesifik

Coba sendiri

Dispatch method dan status code, bentuk yang dimiliki setiap endpoint HTTP.

const requests = [
  ["GET", { id: 1 }],
  ["GET", { id: 999 }],
  ["POST", { session: null, body: { name: "New" } }],
  ["POST", { session: { userId: 7 }, body: { name: "x" } }],
  ["POST", { session: { userId: 7 }, body: { name: "Villa Rain" } }],
  ["DELETE", { session: { userId: 99 } }],
  ["DELETE", { session: { userId: 7 } }],
  ["PATCH", {}],
];

for (const [method, req] of requests) {
  const res = route(method, req);
  const extra = res.allow ? "  Allow: " + res.allow.join(", ") : "";
  console.log(method.padEnd(7) + String(res.status).padEnd(5) + JSON.stringify(res.body) + extra);
}

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Tugas praktik

Tambahkan Route Handler ke proyek ini di app/api/health/route.ts yang mengembalikan Response.json({ ok: true, lessons: TOTAL_LESSONS }). Buka /api/health di browser-mu, lalu panggil dengan curl -i dan baca status serta header-nya. Lalu tambahkan POST yang mengembalikan 405 dan pastikan curl -X POST -i menampilkannya.

Hasil yang diharapkan

200 dengan JSON, dan 405 untuk method yang salah.