API Routes: Membuat Endpoint Sendiri

Kapan butuh API Routes?

Server Actions cukup untuk form dan aksi dari UI-mu sendiri. Tapi kalau butuh endpoint yang dipanggil pihak luar (webhook, aplikasi mobile, integrasi pihak ketiga), kamu butuh Route Handler: file route.ts.

Membuat endpoint

// app/api/produk/route.ts
import { NextResponse } from "next/server";

const produk = [
  { id: 1, nama: "Kopi Susu" },
  { id: 2, nama: "Teh Manis" },
];

export async function GET() {
  return NextResponse.json(produk);
}

export async function POST(request: Request) {
  const body = await request.json();
  const baru = { id: Date.now(), nama: body.nama };
  produk.push(baru);
  return NextResponse.json(baru, { status: 201 });
}

File ini otomatis menjadi endpoint GET /api/produk dan POST /api/produk. Export fungsi dengan nama method HTTP yang didukung: GET, POST, PUT, PATCH, DELETE.

Membaca parameter dan query

// app/api/produk/[id]/route.ts
import { NextResponse } from "next/server";

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const url = new URL(request.url);
  const detail = url.searchParams.get("detail"); // ?detail=penuh
  return NextResponse.json({ id, detail });
}

Route Handler vs Server Actions

Gunakan Route Handler untuk: webhook, API publik, dan response non-JSON (file, gambar). Gunakan Server Action untuk: form, mutasi data dari UI sendiri. Jangan bikin API hanya untuk dipanggil Server Component-mu sendiri, itu pemborosan satu lapis network.

Kesalahan umum pemula

• Membuat API hanya untuk dipanggil Server Component sendiri. Ini menambah satu hop network yang tidak perlu. Panggil fungsi/logikanya langsung.
• Tidak menangani method yang tidak didukung. Kalau hanya ada GET, request POST akan 404 membingungkan. Pertimbangkan response 405 yang jelas.
• Lupa validasi body POST. Sama seperti Server Action, body dari request.json() tidak terpercaya. Validasi dengan Zod.

Latihan singkat

1. Buat GET /api/status yang mengembalikan { "ok": true, "waktu": "..." }.
2. Buat POST /api/echo yang menerima JSON, memvalidasi field pesan (string min 1 karakter), lalu mengembalikannya.

Rangkuman

• Route Handler (route.ts) membuat REST endpoint untuk webhook, API publik, dan response non-JSON.
• Export fungsi bernama sesuai method HTTP: GET, POST, PUT, PATCH, DELETE.
• Untuk form dan aksi UI sendiri, Server Action lebih sederhana.
• Jangan membuat API hanya untuk dipanggil Server Component-mu sendiri.

Catatan teknis: Route Handler yang memakai request (membaca header, cookie, atau searchParams) otomatis menjadi dinamis dan tidak di-cache. Ini benar untuk data real-time, tapi jangan heran kalau endpoint-mu selalu "segar" padahal kamu berharap di-cache.