API Versioning

Apa itu API Versioning

• Praktik mengelola perubahan API dengan mempertahankan versi lama
• Memungkinkan perubahan fitur tanpa merusak aplikasi yang sudah jalan
• Consumer bisa bermigrasi ke versi baru sesuai jadwal mereka

Mengapa Versioning Penting

• API akan berubah seiring bertambahnya fitur
• Tidak semua consumer bisa update secara bersamaan
• Breaking change tanpa versioning akan merusak aplikasi produksi
• Versioning memberikan waktu transisi yang aman

Strategi Versioning

URL Path Versioning

• Versi ditulis di URL, contoh: /v1/users, /v2/users
• Paling umum dan mudah dipahami
• Mudah untuk dokumentasi dan testing
• Contoh: /api/v1/users dan /api/v2/users

Header Versioning

• Versi dikirim melalui HTTP header
• URL tetap bersih tanpa versi
• Contoh: Accept: application/vnd.api.v1+json
• Lebih rumit untuk dipahami dan didokumentasikan

Query Parameter Versioning

• Versi dikirim sebagai query parameter
• Contoh: /users?version=2
• Mudah untuk testing tapi kurang elegan
• Jarang digunakan dalam praktik modern

Jenis Perubahan API

Breaking Change

• Mengubah format response yang sudah ada
• Menghapus field yang sudah dipakai
• Mengubah nama endpoint
• Mengubah tipe data field
• Breaking change memerlukan versi baru

Non-Breaking Change

• Menambah field baru di response
• Menambah endpoint baru
• Memperbaiki bug tanpa mengubah kontrak
• Non-breaking change tidak memerlukan versi baru

Deprecation

• Menandai versi lama tidak akan dikembangkan lagi
• Beri notice dengan header Deprecation
• Beri timeline kapan versi lama akan dihapus
• Pantau penggunaan versi lama untuk menentukan waktu penghapusan

Contoh Deprecation Header

Deprecation: true
Sunset: Sat, 01 Jan 2025 00:00:00 GMT

Praktik Terbaik Versioning

• Mulai versioning sejak API pertama kali dirilis
• Jangan pernah mengubah versi yang sudah stabil
• Dokumentasikan perbedaan antar versi dengan jelas
• Beri timeline yang cukup untuk migrasi
• Hapus versi lama hanya setelah penggunaannya sangat rendah
• Gunakan semantic versioning untuk internal tracking: major.minor.patch

Contoh Struktur Kode dengan Versioning

src/
  api/
    v1/
      users.js
      orders.js
    v2/
      users.js
      orders.js

Versioning dan Database

• Database umumnya tidak perlu versioning bersama API
• Gunakan kolom atau tabel tambahan untuk data versi baru
• Pertahankan backward compatibility di level data jika memungkinkan