API Design di Next.js – Route Handlers yang Clean & Maintainable
— NextJS, API, Route-Handlers, Backend — 2 min read
API Design di Next.js – Route Handlers yang Clean & Maintainable
Halo teman-teman,
Semakin project tumbuh, semakin penting bagaimana kita mendesain API-nya. Di Next.js App Router, Route Handlers jadi tempat utama untuk backend logic. Setelah beberapa kali refactor, ini pendekatan yang paling sering saya pakai.
1. Struktur Folder yang Rapi
Saya suka memisahkan berdasarkan resource:
/app /api /users /route.ts /[id] /route.ts /invoices /route.tsAtau kalau pakai feature-based:
/features /users /api /route.ts2. Consistent Response Format
Saya selalu return format yang konsisten:
// Successreturn Response.json({ data: user }, { status: 200 });
// Errorreturn Response.json( { error: { message: "User not found", code: "USER_NOT_FOUND" } }, { status: 404 },);3. Validation dengan Zod
Setiap input wajib divalidasi:
import { z } from "zod";
const createUserSchema = z.object({ name: z.string().min(2), email: z.string().email(),});
export async function POST(request: Request) { const body = await request.json(); const parsed = createUserSchema.safeParse(body);
if (!parsed.success) { return Response.json( { error: { message: "Invalid input", details: parsed.error.flatten() } }, { status: 400 }, ); }
// lanjut proses...}4. Error Handling yang Konsisten
Saya pakai custom error class + central handler supaya response error seragam di seluruh API.
5. Hal yang Saya Hindari
- Mencampur business logic terlalu banyak di dalam Route Handler
- Mengembalikan data mentah tanpa struktur
- Lupa validasi input
- Status code yang tidak konsisten
Kesimpulan
API yang baik bukan hanya “bisa jalan”, tapi mudah dipahami, mudah di-test, dan mudah diubah.
Kalau Route Handlers kalian mulai terasa berantakan, coba mulai dari consistent response format + Zod validation dulu. Biasanya sudah cukup bikin perbedaan besar.
Pertanyaan buat kalian:
Bagaimana cara kalian struktur API di Next.js sekarang?
Pakai Route Handlers murni atau ada layer service terpisah?
Cerita di komentar yuk!
— Ady Rahmansyah
Software Engineer | Tech Blogger | Coffee Addict