Skip to content
Algol Blog

API Design di Next.js – Route Handlers yang Clean & Maintainable

— NextJS, API, Route-Handlers, Backend — 2 min read

api-design-nextjs

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.ts

Atau kalau pakai feature-based:

/features
/users
/api
/route.ts

2. Consistent Response Format

Saya selalu return format yang konsisten:

// Success
return Response.json({ data: user }, { status: 200 });
// Error
return 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

© 2026 by Algol Blog. All rights reserved.
Theme by LekoArts