Penentuan versi pada REST API (API Versioning) melalui URL adalah metode paling populer dan transparan untuk memastikan perubahan kode pada server tidak merusak aplikasi klien yang sudah berjalan. Pendekatan ini menempatkan nomor versi, seperti v1 atau v2, langsung di dalam struktur path URL endpoint (contoh: https://api.domain.com/v1/users).
Meskipun terdapat beberapa metode lain seperti Header Versioning (Accept header) atau Query Parameter Versioning (?version=1), penggunaan URL path tetap menjadi favorit karena kemudahan dalam pengujian langsung melalui peramban, kejelasan pembagian rute pada framework backend, serta kesederhanaan proses debugging bagi pengembang.
Metode Penentuan Versi API
Berikut adalah perbandingan tiga metode utama dalam penerapan versi REST API yang umum digunakan dalam arsitektur perangkat lunak modern:
| Metode Versioning | Contoh Implementasi | Kelebihan | Kekurangan |
|---|---|---|---|
| URL Path Versioning | /api/v1/resource |
Sangat jelas, mudah diuji di browser, mudah di-routing. | Melanggar prinsip URI murni karena versi dianggap bagian dari identitas sumber daya. |
| Header Versioning | Accept: application/vnd.company.v1+json |
URL bersih, sesuai dengan prinsip RESTful murni. | Sulit diuji langsung di browser, butuh tools khusus seperti Postman. |
| Query Parameter | /api/resource?version=1 |
Mudah diterapkan, mendukung cache berbasis URL dengan konfigurasi tertentu. | Rawan terlewat oleh klien, sulit dikelola jika parameter bertumpuk. |
Standar Penamaan Format URL Versioning
Dalam membangun REST API dengan versi berbasis URL, konsistensi penamaan adalah kunci utama pemeliharaan jangka panjang. Gunakan format huruf kecil dengan awalan huruf 'v' diikuti nomor mayor (misalnya v1, v2). Penomoran mayor ini hanya berubah jika terjadi perombakan besar atau perubahan yang memutus kompatibilitas (breaking changes).
// Contoh struktur URL REST API yang disarankan
GET https://api.example.com/v1/products
POST https://api.example.com/v1/products
GET https://api.example.com/v1/products/452
PUT https://api.example.com/v1/products/452
DELETE https://api.example.com/v1/products/452Aturan dan Kebijakan Pemeliharaan Versi
Penerapan versi URL harus diiringi dengan kebijakan siklus hidup (lifecycle policy) yang jelas bagi pengembang pihak ketiga maupun internal tim:
- Hindari Perubahan Minor pada URL: Perubahan kecil seperti penambahan field opsional pada JSON response tidak memerlukan pembuatan versi baru (
v2). Cukup gunakan versi yang sama karena klien lama akan mengabaikan field baru tersebut. - Dokumentasi Terpisah: Setiap versi URL wajib memiliki dokumentasi endpoint yang terisolasi untuk memudahkan migrasi klien.
- Masa Transisi (Deprecation Period): Ketika merilis
v2, beri rentang waktu minimal 6 bulan hingga 1 tahun sebelum mematikan total endpointv1, disertai header peringatanDeprecation: truepada respons server.
Troubleshooting Routing dan Middleware
Dalam implementasi teknis di backend (seperti Node.js/Express, Laravel, atau Spring Boot), pastikan Anda memisahkan kontroler berdasarkan versinya. Hal ini mencegah kode menjadi kotor akibat terlalu banyak percabangan kondisi (if-else) di dalam satu fungsi controller yang sama.
// Contoh struktur routing modular di Express.js
const express = require('express');
const app = express();
const v1Routes = require('./routes/v1');
const v2Routes = require('./routes/v2');
app.use('/api/v1', v1Routes);
app.use('/api/v2', v2Routes);
app.listen(3000, () => {
console.log('Server berjalan pada port 3000');
});