# API Versioning di NestJS: Strategi yang Benar-benar Saya Kirim > Cara mengimplementasikan versioning API berbasis URI di NestJS tanpa merusak klien yang ada — dengan pola controller dan strategi migrasi yang saya gunakan. URL: https://www.matthewswong.com/id/blog/api-versioning-nestjs-strategy/ - Author: Matthews Wong (https://www.matthewswong.com/id/about/) - Published: 2025-06-10 - Updated: 2025-06-10 - Category: Web Dev Perubahan API yang merusak adalah setara developer dengan menarik taplak meja — semuanya jatuh. Saya telah mengirimkan tiga versi utama API ERP sambil mempertahankan kompatibilitas backward untuk klien yang belum bermigrasi. Tooling di NestJS membuat versioning mudah diimplementasikan, tetapi bagian yang sulit adalah strategi migrasi: bagaimana Anda menghentikan v1 tanpa merusak integrasi? ## Dukungan Versioning Bawaan NestJS NestJS 8+ memiliki versioning API native bawaan di framework, mendukung empat strategi: URI versioning (/v1/users, /v2/users), Header versioning (header permintaan kustom seperti X-API-Version), Media Type versioning (parameter versi header Accept), dan Custom versioning (fungsi apa pun yang mengekstrak versi dari permintaan). Anda mengaktifkan versioning dalam fungsi bootstrap dengan satu baris. ### URI Versioning: Pilihan Default URI versioning menyematkan versi di jalur URL: `/api/v1/invoices`, `/api/v2/invoices`. Ini adalah strategi yang paling terlihat dan eksplisit — klien tahu versi mana yang mereka panggil dari URL saja, log mudah difilter berdasarkan versi, dan alat dokumentasi API (Swagger) dapat menghasilkan dokumen terpisah per versi. ### Header Versioning: Untuk URL yang Lebih Bersih Header versioning menjaga URL tetap bersih — `/api/invoices` terlepas dari versi — dan menggunakan header kustom seperti `X-API-Version: 2` untuk memilih versi. Saya menggunakan URI versioning untuk API eksternal dan header versioning untuk API internal layanan-ke-layanan di mana saya mengontrol kedua sisi. > Dari pengalaman saya mengelola versi API di proyek ERP: gunakan VERSION_NEUTRAL untuk endpoint bersama yang tidak berubah antar versi. Daripada menduplikasi handler rute di setiap controller versi, tandai endpoint stabil dengan `@Version(VERSION_NEUTRAL)` — mereka merespons permintaan terlepas dari versi apa yang ditentukan klien. Endpoint GET /api/health, misalnya, tidak memerlukan varian v1/v2. ## Arsitektur Controller untuk Beberapa Versi Pendekatan terbersih untuk API NestJS yang diversion adalah menjaga logika bisnis di lapisan layanan dan mengeksposnya melalui controller spesifik versi. Controller Version 1 dan Version 2 dapat berbagi layanan yang sama, hanya memanggil metode yang berbeda atau meneruskan DTO yang berbeda. Ini mencegah antipattern menduplikasi logika bisnis di seluruh controller versi. ### Dokumentasi Swagger per Versi Saat menggunakan @nestjs/swagger dengan API yang diversion, konfigurasikan dokumen Swagger terpisah per versi API. Setiap DocumentBuilder mendapatkan base path sendiri — `/api/v1` untuk v1, `/api/v2` untuk v2. Ini memberi Anda UI Swagger /api-docs/v1 dan /api-docs/v2 yang terpisah. > **Jangan Pernah Hapus Route Lama Sampai Semua Klien Telah Bermigrasi** > Kesalahan versioning API terbesar adalah menghapus rute v1 sebelum semua klien pindah ke v2. Bahkan jika Anda telah mengkomunikasikan tanggal penghentian, integrasi rusak. Pendekatan yang aman: tambahkan catatan `@Deprecated()` di dokumen Swagger v1, tambahkan header respons seperti `Deprecation: true; date='2026-01-01'`, catat penggunaan endpoint yang tidak digunakan lagi, dan hanya hapus ketika penggunaan turun ke nol. ## Logika Deteksi dan Routing Versi Router NestJS mencocokkan rute dalam urutan spesifisitas. Jika tidak ada controller v2 yang ada untuk rute itu, NestJS tidak fallback ke v1 — mengembalikan 404. Ini berarti Anda harus secara eksplisit mengimplementasikan setiap endpoint yang diversion. Untuk migrasi bertahap di mana v2 sebagian besar sama dengan v1, buat controller v2 yang memperluas controller v1 dan hanya menimpa metode yang berubah. ## Strategi Migrasi: Cara Saya Menghentikan API Proses penghentian API saya: 1) Kirim v2 bersama v1 — keduanya berfungsi penuh. 2) Perbarui dokumen API untuk menandai endpoint v1 sebagai tidak digunakan lagi dengan panduan migrasi. 3) Tambahkan header Sunset ke respons v1. 4) Tambahkan logging untuk menghitung panggilan endpoint v1 per klien. 5) Email klien yang masih menggunakan v1 dengan tenggat waktu migrasi. 6) Seminggu sebelum sunset, kembalikan error 429 untuk permintaan v1. 7) Hapus kode v1 pada tanggal sunset. ## Versioning untuk API Internal vs Eksternal API internal layanan-ke-layanan dalam monorepo atau sistem microservices tidak memerlukan disiplin versioning yang sama dengan API eksternal. Jika Anda mengontrol produsen dan semua konsumen, Anda dapat menggunakan semantic versioning dengan deployment terkoordinasi. API eksternal (dikonsumsi oleh aplikasi mobile, integrasi pihak ketiga, atau pengembang publik) memerlukan versioning ketat, jendela penghentian yang panjang, dan jaminan kompatibilitas backward. ## Sumber & Bacaan Lebih Lanjut - NestJS — Versioning Documentation - This Dot Labs — NestJS API Versioning Strategies - Medium — Mastering API Versioning with NestJS ## Source links - https://docs.nestjs.com/techniques/versioning - https://www.thisdot.co/blog/nestjs-api-versioning-strategies - https://medium.com/@slimbennasrallah_89177/mastering-api-versioning-with-nestjs-3a9b1c6bac56 ## FAQ ### Strategi versioning API apa yang didukung NestJS, dan mana yang direkomendasikan untuk API publik? NestJS 8+ mendukung empat strategi secara native: URI versioning (/v1/users, /v2/users), Header versioning (header X-API-Version), Media Type versioning (parameter header Accept), dan Custom versioning. URI versioning adalah pilihan yang direkomendasikan untuk API publik karena paling eksplisit — klien dapat mengetahui versi yang dipanggil hanya dari URL, log mudah difilter berdasarkan versi, dan Swagger dapat menghasilkan dokumentasi terpisah per versi. ### Apa itu VERSION_NEUTRAL dan kapan sebaiknya digunakan? VERSION_NEUTRAL adalah nilai dekorator khusus di NestJS yang menandai endpoint agar merespons permintaan terlepas dari versi apa pun yang ditentukan klien. Sebaiknya digunakan untuk endpoint stabil yang tidak berubah antar versi — seperti GET /api/health — sehingga Anda tidak perlu menduplikasi handler rute yang sama di setiap controller versi. ### Bagaimana cara mengelola dokumentasi Swagger saat menjalankan beberapa versi API sekaligus? Konfigurasikan dokumen Swagger terpisah untuk setiap versi API menggunakan DocumentBuilder dengan base path masing-masing (/api/v1 untuk v1, /api/v2 untuk v2). SwaggerModule.createDocument menerima opsi include untuk memfilter rute per versi, menghasilkan UI Swagger /api-docs/v1 dan /api-docs/v2 yang terpisah sehingga klien hanya melihat endpoint yang relevan dengan versinya. ### Apa proses yang aman untuk menghentikan API v1 tanpa merusak integrasi yang sudah ada? Post ini menguraikan proses tujuh langkah: kirim v2 bersama v1 saat keduanya masih berfungsi penuh, tandai endpoint v1 sebagai deprecated di dokumentasi disertai panduan migrasi, tambahkan header Sunset pada respons v1, catat penggunaan v1 per klien, kirim email ke klien yang masih menggunakan v1 beserta tenggat waktu migrasi, kembalikan error 429 seminggu sebelum sunset, dan hapus kode v1 pada tanggal sunset. Untuk API eksternal, proses ini biasanya memakan waktu 3–6 bulan. ### Apakah NestJS otomatis fallback ke controller versi lama jika rute yang diversion tidak ditemukan? Tidak. Jika permintaan masuk untuk /api/v2/invoices dan tidak ada controller v2 untuk rute tersebut, NestJS mengembalikan 404 — tidak ada fallback ke v1. Setiap endpoint yang diversion harus diimplementasikan secara eksplisit. Untuk migrasi bertahap di mana v2 sebagian besar sama dengan v1, Anda dapat membuat controller v2 yang memperluas controller v1 dan hanya menimpa metode yang berubah. --- - HTML version: https://www.matthewswong.com/id/blog/api-versioning-nestjs-strategy/ - English: https://www.matthewswong.com/en/blog/api-versioning-nestjs-strategy/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json