Cara membuat versioning API Express Node JS paling aman adalah menduplikat router per versi, lalu mendaftarkannya dengan prefix berbeda seperti /api/v1/users dan /api/v2/users. Kedua versi berjalan paralel, jadi klien lama tidak rusak saat kamu merilis struktur respons baru.
Kebutuhan Versioning API Express
Pola ini memakai Node.js dengan Express dan sistem modul CommonJS. Pisahkan file router agar perubahan v2 tidak menyentuh logika v1.
- Node.js dan Express terinstal, gunakan require() dan module.exports.
- Struktur folder routes/v1/users.js dan routes/v2/users.js.
- Respons JSON konsisten, misalnya { data: […] } di semua versi.
Versi dibaca dari path URL lewat req.params atau prefix statis. Jangan membaca versi dari req.query seperti ?version=2 karena query string mudah hilang saat caching dan tidak cocok untuk routing permanen.
Langkah Membuat Versioning API di Express
1. Buat file router v1 dan v2 terpisah dengan express.Router(). Isi tiap file hanya endpoint versi itu.
2. Daftarkan prefix /api/v1 dan /api/v2 di app.js. Express meneruskan request ke router yang sesuai prefix.
3. Uji kedua versi berjalan paralel tanpa breaking change. Panggil keduanya dengan curl atau Postman dan pastikan status code tetap 200.
const express = require('express');
const app = express();
app.use(express.json());
const v1Users = require('./routes/v1/users');
const v2Users = require('./routes/v2/users');
app.use('/api/v1/users', v1Users);
app.use('/api/v2/users', v2Users);
app.listen(3000);
// routes/v1/users.js
const express = require('express');
const router = express.Router();
router.get('/', (req, res) => {
res.json({ data: [{ id: 1, name: 'Budi' }] });
});
module.exports = router;
Tabel Komponen Versioning API
| Komponen | Fungsi | Contoh |
|---|---|---|
| Router v1 | Menampung kontrak lama | /api/v1/users |
| Router v2 | Menampung kontrak baru | /api/v2/users |
| Prefix versi | Memisahkan traffic | app.use(‘/api/v1’) |
Tambah v2 hanya saat kamu menghapus field, mengubah tipe data, atau mengubah validasi secara tidak kompatibel. Jika hanya menambah field baru yang opsional, cukup perbarui v1.
Validasi input dan status code harus identik antar versi. Kembalikan 400 untuk input salah dan 404 untuk data tidak ada di v1 maupun v2.
FAQ
Apakah versi lama harus dihapus setelah v2 rilis?
Tidak. Pertahankan v1 sampai tidak ada klien aktif, lalu umumkan masa deprecated.
Lebih baik versioning lewat URL atau header?
URL seperti /api/v1 lebih jelas untuk debugging dan caching, header hanya cocok untuk API internal yang kompleks.