TeknoTUT

Membuat REST API dengan Node.js dan Express 5 untuk Pemula

Panduan membuat REST API dengan Node.js dan Express 5 dari nol: routing, CRUD, validasi, error handling, hingga pengujian dengan curl.

Ditulis oleh 12 menit bacaEnglish
Ilustrasi server API yang bertukar data JSON dengan laptop dan ponsel
Daftar Isi

Jika anda adalah seorang developer web, tentu anda sudah tidak asing dengan istilah API. Aplikasi mobile yang menampilkan daftar produk, dashboard yang memuat grafik, hingga perangkat IoT yang mengirim data sensor, hampir semuanya berbicara dengan server melalui API.

Masalahnya, bagi pemula, membuat API sendiri sering terasa rumit. Harus mulai dari mana? Bagaimana cara menerima data JSON? Kode status apa yang harus dikembalikan? Belum lagi banyak tutorial di internet yang masih memakai cara lama dan sudah tidak sesuai dengan versi terbaru.

Di sinilah Express berperan. Express adalah framework web paling populer di Node.js, dan sejak Express 5 menjadi versi default di npm, ada beberapa perubahan penting yang membuat kode kita lebih ringkas, terutama saat menangani error.

Dalam artikel kali ini, kita akan membahas tuntas cara membuat REST API dengan Node.js dan Express 5, mulai dari menyiapkan project, membuat endpoint CRUD, memvalidasi input, menangani error, hingga mengujinya dengan curl. Mari kita mulai!

Apa itu REST API?

API (Application Programming Interface) adalah "pintu" yang disediakan sebuah aplikasi agar aplikasi lain bisa meminta atau mengirim data. REST (Representational State Transfer) adalah gaya perancangan API yang memanfaatkan protokol HTTP apa adanya: URL mewakili data (disebut resource), dan method HTTP mewakili aksi terhadap data tersebut.

Bayangkan sebuah restoran. Anda (client) tidak masuk ke dapur (database), melainkan memesan lewat pelayan (API) dengan cara yang sudah disepakati. Pelayan lalu membawakan hasilnya, biasanya dalam format JSON.

Pada REST API, setiap method HTTP punya peran yang jelas:

Method Contoh Endpoint Fungsi Kode Status Sukses
GET /todos Mengambil semua data 200 OK
GET /todos/1 Mengambil satu data 200 OK
POST /todos Membuat data baru 201 Created
PATCH /todos/1 Mengubah sebagian data 200 OK
DELETE /todos/1 Menghapus data 204 No Content

Kelima endpoint di atas itulah yang akan kita buat di artikel ini, dalam bentuk API daftar tugas (todo list) sederhana.

Mengapa Menggunakan Express 5?

Node.js sebenarnya bisa membuat server HTTP tanpa framework apa pun. Namun, anda harus mengurai URL, membaca body request, dan mengatur routing secara manual. Express membereskan semua itu dengan API yang sangat sederhana.

Beberapa alasan memilih Express 5:

  • Ringan dan minimalis: Express hanya menyediakan routing dan middleware. Sisanya anda yang menentukan, sehingga cocok untuk belajar karena tidak ada "sihir" yang tersembunyi.
  • Ekosistem sangat besar: hampir semua kebutuhan (autentikasi, upload file, CORS, rate limiting) sudah ada middleware-nya.
  • Error pada fungsi async ditangani otomatis: di Express 5, promise yang ditolak (rejected) di dalam handler otomatis diteruskan ke middleware penanganan error. Di Express 4, anda harus membungkusnya sendiri dengan try...catch.
  • Sudah menjadi versi default: perintah npm install express kini memasang Express 5. Saat artikel ini ditulis, versi terbarunya adalah 5.3.

Kekurangan yang Perlu Diketahui

Agar berimbang, ada beberapa hal yang perlu anda ketahui:

  • Tidak ada struktur baku: Express tidak mengatur susunan folder atau cara validasi. Untuk project besar, anda perlu disiplin sendiri (atau memakai framework yang lebih lengkap seperti NestJS).
  • Banyak tutorial lama: sebagian besar tutorial di internet ditulis untuk Express 4. Beberapa sintaks, seperti rute wildcard /*, sudah tidak berlaku di Express 5. Kita akan membahas perbedaannya di bagian akhir.

Persiapan

Sebelum memulai, pastikan anda sudah memiliki:

  • Node.js versi 18 atau lebih baru, karena itulah syarat minimum Express 5. Sangat disarankan memakai versi LTS, yaitu Node.js 24 atau Node.js 26. Perintah node --watch yang dipakai di artikel ini membutuhkan Node.js 22 ke atas. Jika belum terpasang, silakan ikuti artikel cara install Node.js.
  • Terminal dan text editor seperti VS Code.
  • curl untuk menguji API. Aplikasi ini sudah tersedia di macOS, sebagian besar distro Linux, dan Windows 10/11.

Periksa versi Node.js dan npm anda dengan perintah berikut:

node --version
npm --version

Jika outputnya menampilkan nomor versi (misalnya v24.x.x), berarti anda siap melanjutkan. Kode di artikel ini ditujukan untuk Express 5 dengan Node.js 22 ke atas.

Cara Membuat REST API dengan Express 5

Langkah #1: Buat Project Baru

Buat folder project, lalu masuk ke dalamnya:

mkdir todo-api
cd todo-api

Inisialisasi project Node.js dengan perintah berikut. Opsi -y membuat file package.json dengan nilai default tanpa banyak pertanyaan.

npm init -y

Di artikel ini kita memakai sintaks ES Modules (import), yaitu standar modul JavaScript modern. Aktifkan dengan mengatur type menjadi module di package.json:

npm pkg set type=module

Terakhir, pasang Express:

npm install express

Untuk memastikan yang terpasang adalah Express 5, jalankan perintah berikut:

npm list express

Outputnya kira-kira seperti ini:

[email protected] /home/budi/todo-api
└── [email protected]

Jika angka depannya 5, berarti anda sudah memakai Express 5.

Langkah #2: Buat Server Pertama

Buat file app.js di dalam folder project, lalu isi dengan kode berikut:

import express from "express";
 
const app = express();
const PORT = process.env.PORT || 3000;
 
app.get("/", (req, res) => {
  res.json({ message: "Todo API is running" });
});
 
app.listen(PORT, (error) => {
  if (error) throw error;
  console.log(`Server running at http://localhost:${PORT}`);
});

Penjelasan singkat kode di atas:

  • express() membuat aplikasi Express.
  • app.get("/", ...) mendaftarkan route: ketika ada request GET ke /, jalankan fungsi di belakangnya. Fungsi ini disebut handler dan menerima req (request) serta res (response).
  • res.json() mengirim response dalam format JSON, lengkap dengan header Content-Type yang benar.
  • app.listen() menjalankan server di port yang ditentukan. Di Express 5, callback-nya juga menerima error, misalnya ketika port sudah dipakai aplikasi lain.

Jalankan server dengan perintah berikut:

node --watch app.js

Opsi --watch membuat Node.js otomatis me-restart server setiap kali file berubah, sehingga anda tidak perlu lagi memasang nodemon. Biarkan terminal ini tetap terbuka.

Buka terminal baru, lalu uji dengan curl:

curl http://localhost:3000/

Jika outputnya seperti di bawah ini, selamat, server pertama anda sudah berjalan!

{"message":"Todo API is running"}

Langkah #3: Siapkan Data dan Middleware JSON

Agar tetap fokus pada Express, kita akan menyimpan data di dalam array di memori. Tambahkan kode berikut di app.js, tepat di bawah baris const PORT:

app.use(express.json());
 
let nextId = 3;
const todos = [
  { id: 1, title: "Learn Express", done: true },
  { id: 2, title: "Build a REST API", done: false },
];

Baris app.use(express.json()) memasang middleware bawaan Express yang membaca body request berformat JSON, lalu menyimpannya di req.body. Middleware adalah fungsi yang dijalankan sebelum request sampai ke handler, mirip pos pemeriksaan yang dilewati setiap request.

Catatan: karena data hanya disimpan di memori, semua perubahan akan hilang setiap kali server di-restart. Ini tidak masalah untuk belajar. Untuk aplikasi sungguhan, gantilah array ini dengan database seperti SQLite, PostgreSQL, atau MongoDB.

Langkah #4: Buat Endpoint untuk Membaca Data (GET)

Sekarang kita buat dua endpoint: satu untuk mengambil semua tugas, satu lagi untuk mengambil satu tugas berdasarkan id. Tambahkan kode berikut di atas baris app.listen:

app.get("/todos", (req, res) => {
  const { done } = req.query;
  if (done === undefined) return res.json(todos);
  res.json(todos.filter((todo) => String(todo.done) === done));
});
 
app.get("/todos/:id", (req, res) => {
  const todo = todos.find((item) => item.id === Number(req.params.id));
  if (!todo) return res.status(404).json({ error: "Todo not found" });
  res.json(todo);
});

Ada dua hal baru di sini:

  • req.query berisi query string dari URL. Dengan begitu, /todos?done=true hanya mengembalikan tugas yang sudah selesai.
  • :id adalah route parameter. Nilainya tersedia di req.params.id dalam bentuk string, sehingga kita ubah menjadi angka dengan Number().

Jika tugas tidak ditemukan, kita mengembalikan kode status 404 beserta pesan error. Mengembalikan kode status yang tepat adalah salah satu ciri REST API yang baik.

Uji kedua endpoint tersebut:

curl http://localhost:3000/todos
curl http://localhost:3000/todos/2
curl "http://localhost:3000/todos?done=true"

Output perintah pertama kira-kira seperti ini:

[{"id":1,"title":"Learn Express","done":true},{"id":2,"title":"Build a REST API","done":false}]

Langkah #5: Buat Endpoint untuk Menambah Data (POST)

Endpoint berikutnya menerima data JSON dari client. Tambahkan kode berikut di bawah endpoint GET tadi:

app.post("/todos", (req, res) => {
  const title = req.body?.title;
  if (typeof title !== "string" || title.trim() === "") {
    return res.status(400).json({ error: "Field 'title' is required" });
  }
 
  const todo = { id: nextId++, title: title.trim(), done: false };
  todos.push(todo);
  res.status(201).json(todo);
});

Jangan pernah langsung percaya pada data yang dikirim client. Di sini kita melakukan validasi sederhana: title harus berupa string dan tidak boleh kosong. Jika tidak valid, kita mengembalikan 400 Bad Request. Jika valid, kita mengembalikan 201 Created beserta data yang baru dibuat.

Kenapa req.body?.title, bukan req.body.title? Di Express 5, req.body bernilai undefined jika body tidak di-parse, misalnya ketika client lupa mengirim header Content-Type: application/json. Di Express 4, nilainya {}. Tanpa tanda ?., kode kita akan melempar error dan client menerima 500, padahal yang salah adalah request-nya.

Uji dengan mengirim data JSON. Opsi -i menampilkan header response agar kode statusnya terlihat:

curl -i -X POST http://localhost:3000/todos -H "Content-Type: application/json" -d '{"title":"Deploy to VPS"}'

Bagian penting dari outputnya kira-kira seperti ini:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
 
{"id":3,"title":"Deploy to VPS","done":false}

Pengguna Windows: tanda kutip tunggal pada perintah di atas tidak dikenali oleh Command Prompt. Jalankan curl dari Git Bash atau WSL, atau gunakan aplikasi seperti Postman.

Coba juga kirim body kosong dengan -d '{}'. Anda seharusnya mendapatkan 400 Bad Request dengan pesan Field 'title' is required.

Langkah #6: Buat Endpoint untuk Mengubah dan Menghapus Data (PATCH & DELETE)

Untuk mengubah data, kita memakai PATCH karena client boleh mengirim sebagian field saja (misalnya hanya done). Tambahkan kode berikut:

app.patch("/todos/:id", (req, res) => {
  const todo = todos.find((item) => item.id === Number(req.params.id));
  if (!todo) return res.status(404).json({ error: "Todo not found" });
 
  const { title, done } = req.body ?? {};
  if (title !== undefined) {
    if (typeof title !== "string" || title.trim() === "") {
      return res.status(400).json({ error: "Field 'title' must be a non-empty string" });
    }
    todo.title = title.trim();
  }
  if (done !== undefined) {
    if (typeof done !== "boolean") {
      return res.status(400).json({ error: "Field 'done' must be a boolean" });
    }
    todo.done = done;
  }
 
  res.json(todo);
});
 
app.delete("/todos/:id", (req, res) => {
  const index = todos.findIndex((item) => item.id === Number(req.params.id));
  if (index === -1) return res.status(404).json({ error: "Todo not found" });
 
  todos.splice(index, 1);
  res.status(204).end();
});

Pada endpoint DELETE, kita mengembalikan 204 No Content: artinya berhasil, tetapi tidak ada isi yang perlu dikirim balik. Karena itu kita memakai .end(), bukan .json().

Tandai tugas nomor 2 sebagai selesai, lalu hapus tugas nomor 1:

curl -X PATCH http://localhost:3000/todos/2 -H "Content-Type: application/json" -d '{"done":true}'
curl -i -X DELETE http://localhost:3000/todos/1

Perintah pertama mengembalikan data tugas dengan "done":true, dan perintah kedua menampilkan HTTP/1.1 204 No Content.

Langkah #7: Tangani Rute Tidak Dikenal dan Error

Coba akses alamat yang tidak ada, misalnya curl http://localhost:3000/users. Express akan membalas dengan halaman HTML, padahal client API kita mengharapkan JSON. Hal yang sama terjadi jika client mengirim JSON yang rusak.

Untuk memperbaikinya, tambahkan dua middleware berikut setelah semua route dan sebelum app.listen. Urutan ini penting, karena Express menjalankan middleware dari atas ke bawah.

app.use((req, res) => {
  res.status(404).json({ error: `Route ${req.method} ${req.originalUrl} not found` });
});
 
app.use((err, req, res, next) => {
  if (err.type === "entity.parse.failed") {
    return res.status(400).json({ error: "Invalid JSON body" });
  }
  console.error(err);
  res.status(500).json({ error: "Internal server error" });
});

Middleware pertama menangkap semua request yang tidak cocok dengan route mana pun. Middleware kedua adalah middleware penanganan error. Express mengenalinya dari jumlah parameternya yang harus empat (err, req, res, next), jadi jangan hapus next walaupun tidak dipakai.

Di dalamnya, kita memeriksa err.type. Nilai entity.parse.failed adalah tanda dari express.json() bahwa body yang dikirim bukan JSON yang valid, sehingga kita balas dengan 400. Error lainnya dicatat di log server, dan client hanya menerima pesan umum.

Penting: jangan pernah mengirim err.message atau err.stack ke client di lingkungan produksi. Detail error bisa membocorkan informasi tentang struktur kode dan server anda.

Uji dengan mengirim JSON yang rusak:

curl -X POST http://localhost:3000/todos -H "Content-Type: application/json" -d '{"title":'

Jika outputnya {"error":"Invalid JSON body"}, berarti penanganan error anda sudah bekerja.

Menangani Error pada Handler Async di Express 5

Begitu anda memakai database, hampir semua handler akan menjadi fungsi async. Nah, di sinilah salah satu kelebihan terbesar Express 5 terasa.

Perhatikan contoh berikut, dengan db.findTodos() sebagai contoh fungsi database yang bisa gagal:

app.get("/todos", async (req, res) => {
  const rows = await db.findTodos();
  res.json(rows);
});

Di Express 4, jika db.findTodos() gagal, error-nya tidak tertangkap dan request akan menggantung, kecuali anda membungkusnya dengan try...catch lalu memanggil next(err). Di Express 5, promise yang ditolak otomatis diteruskan ke middleware penanganan error yang kita buat di Langkah #7. Kode menjadi jauh lebih bersih.

Perbedaan Express 5 dan Express 4 yang Sering Menjebak

Jika anda mengikuti tutorial lama atau memindahkan project dari Express 4, perhatikan beberapa perubahan berikut:

Hal Express 4 Express 5
Versi Node.js minimum 0.10 18
Error di handler async Harus try...catch + next(err) Diteruskan otomatis
req.body tanpa parser {} undefined
Rute wildcard /* /*splat (wajib diberi nama)
Parameter opsional /:file.:ext? /:file{.:ext}
req.query Bisa ditimpa Hanya bisa dibaca (getter)
res.send(status), res.json(obj, status) Masih ada Dihapus, pakai res.status(...).json(...)
app.del() Masih ada Dihapus, pakai app.delete()

Daftar lengkapnya bisa anda baca di panduan migrasi Express 5.

Tips Agar REST API Lebih Rapi dan Aman

Tip #1: Pisahkan Route dengan express.Router

Ketika endpoint makin banyak, file app.js akan cepat membengkak. Pindahkan route sejenis ke file tersendiri dengan express.Router(). Contohnya file routes/todos.js:

import { Router } from "express";
 
const router = Router();
 
router.get("/", (req, res) => {
  res.json([]);
});
 
export default router;

Lalu pasang di app.js dengan awalan /todos:

import todosRouter from "./routes/todos.js";
 
app.use("/todos", todosRouter);

Dengan cara ini, path di dalam router cukup ditulis / dan /:id, karena awalan /todos sudah ditentukan saat router dipasang.

Tip #2: Sembunyikan Header X-Powered-By

Secara default, Express mengirim header X-Powered-By: Express di setiap response. Informasi ini memudahkan penyerang mengenali framework yang anda pakai. Matikan dengan satu baris berikut setelah const app = express():

app.disable("x-powered-by");

Tip #3: Simpan Konfigurasi di Environment Variable

Kita sudah menulis process.env.PORT || 3000, sehingga port bisa diganti tanpa mengubah kode. Coba jalankan server di port lain dengan perintah berikut:

PORT=4000 node app.js

Untuk konfigurasi yang lebih banyak (misalnya alamat database), simpan di file .env, lalu jalankan dengan node --env-file=.env app.js. Fitur ini sudah bawaan Node.js, jadi tidak perlu lagi paket dotenv. Jangan lupa memasukkan .env ke .gitignore.

Kesimpulan

Dari artikel ini, kita dapat menyimpulkan bahwa membuat REST API dengan Node.js dan Express 5 ternyata tidak sulit. Dengan satu file dan kurang dari seratus baris kode, kita sudah memiliki API CRUD lengkap dengan validasi input, kode status HTTP yang tepat, serta penanganan rute tidak dikenal dan error dalam format JSON.

Yang Perlu Diingat

  • Pasang express.json() agar body JSON terbaca, dan ingat bahwa req.body bisa bernilai undefined di Express 5.
  • Selalu validasi input, lalu kembalikan kode status yang sesuai: 200, 201, 204, 400, 404, dan 500.
  • Letakkan middleware 404 dan middleware penanganan error paling akhir.
  • Di Express 5, error pada handler async otomatis sampai ke middleware penanganan error.

Langkah Selanjutnya

API yang kita buat masih menyimpan data di memori. Langkah berikutnya yang bisa anda coba adalah menghubungkannya ke database, menambahkan autentikasi, lalu menjalankannya di server.

Untuk menjalankan aplikasi Node.js di VPS, anda bisa mengikuti pola yang sama seperti pada artikel cara deploy Next.js ke VPS dengan PM2 dan Nginx, atau menjadikannya layanan lewat service systemd.


Semoga artikel ini membantu.

Bacaan Selanjutnya

Artikel lain yang mungkin menarik buatmu.