API Versioning di Laravel: Strategi Menjaga Kompatibilitas Saat Aplikasi Berkembang
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Aplikasi mobile versi lama masih dipakai warga berbulan-bulan setelah versi baru rilis. Panduan ini membahas kapan perubahan API dianggap merusak, memilih strategi versi, menyusun kode V1 dan V2 tanpa duplikasi logika, header deprecation dan sunset, pemantauan pemakaian per versi, batas versi minimum aplikasi, dan test kontrak per versi.
Di web, frontend dan backend di-deploy bersamaan. Di aplikasi mobile tidak: setelah Anda merilis versi baru ke Play Store, sebagian warga baru memperbaruinya berminggu-minggu kemudian, dan sebagian lagi tidak pernah. Setiap perubahan API yang merusak (breaking change) langsung membuat aplikasi mereka gagal.
Contoh perubahan yang tampak kecil tetapi merusak:
jumlah iuran diubah dari integer 50000 menjadi objek {"nominal": 50000, "mata_uang": "IDR"},status diganti dari "lunas" menjadi "paid",periode,tanggal diganti nama menjadi tanggal_bayar.Hasil akhir:
/api/v1, /api/v2) dengan struktur kode yang rapi,Deprecation dan Sunset untuk versi lama,| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Laravel Sanctum | 4.x |
| Testing | Pest 4 |
Diasumsikan API v1 sudah dibangun mengikuti artikel Panduan Membuat REST API Laravel Menggunakan API Resource dan Form Request.
| Perubahan | Merusak? | Penanganan |
|---|---|---|
| Menambah field baru di respons | Tidak* | Lakukan di versi yang sama |
| Menambah endpoint baru | Tidak | Lakukan di versi yang sama |
| Menambah parameter opsional | Tidak | Lakukan di versi yang sama |
Menambah nilai enum baru (status: "dispensasi") |
Bisa | Umumkan; klien harus menangani nilai tak dikenal |
| Menghapus atau mengganti nama field | Ya | Versi baru |
Mengubah tipe field (int → object, string → int) |
Ya | Versi baru |
| Mengubah makna field (rupiah → ribuan rupiah) | Ya | Versi baru |
| Menambah parameter wajib | Ya | Versi baru, atau beri nilai bawaan |
| Mengubah status HTTP sukses (200 → 201) | Ya | Versi baru |
| Mengubah format error | Ya | Versi baru |
| Mengubah aturan validasi menjadi lebih ketat | Bisa | Pertimbangkan dampak; umumkan |
* Selama klien tidak memvalidasi respons dengan skema ketat yang menolak field tambahan. Tulis di dokumentasi API bahwa klien wajib mengabaikan field yang tidak dikenal.
Prinsip utamanya: tunda versi baru selama mungkin. Sebagian besar evolusi API bisa dilakukan secara aditif. Versi baru hanya untuk perubahan yang memang tidak bisa dibuat kompatibel.
| Strategi | Contoh | Kelebihan | Kekurangan |
|---|---|---|---|
| URL | /api/v1/iuran |
Jelas, mudah di-cache, mudah diuji di browser dan log | URL berubah antar versi |
| Header kustom | X-Api-Version: 2 |
URL tetap | Tidak terlihat di log akses/URL; mudah lupa dikirim |
| Media type | Accept: application/vnd.rw.v2+json |
Sesuai semantik HTTP | Lebih rumit untuk klien dan dokumentasi |
| Query string | /api/iuran?version=2 |
Mudah | Bercampur dengan parameter filter; mudah dihilangkan proxy/cache |
Untuk aplikasi bisnis dengan klien mobile dan PWA, versi di URL paling praktis dan mudah dipahami tim. Artikel ini memakai strategi tersebut, dengan versi mayor saja (v1, v2), bukan v1.3.2.
Yang berbeda antar versi hanyalah lapisan HTTP: route, controller, Form Request, dan Resource. Model, service, dan aturan bisnis dipakai bersama.
app/
├── Http/
│ ├── Controllers/Api/
│ │ ├── V1/IuranController.php
│ │ └── V2/IuranController.php
│ ├── Requests/Api/
│ │ ├── V1/...
│ │ └── V2/...
│ └── Resources/
│ ├── V1/IuranResource.php
│ └── V2/IuranResource.php
├── Services/ ← dipakai V1 dan V2
└── Models/ ← dipakai V1 dan V2
routes/
└── api/
├── v1.php
└── v2.php
Daftarkan file route per versi:
// bootstrap/app.php
->withRouting(
web: __DIR__.'/../routes/web.php',
commands: __DIR__.'/../routes/console.php',
health: '/up',
then: function () {
foreach (['v1', 'v2'] as $versi) {
Route::middleware(['api', "api.version:{$versi}", 'client.min', 'api.usage'])
->prefix("api/{$versi}")
->name("api.{$versi}.")
->group(base_path("routes/api/{$versi}.php"));
}
},
)
Bila memakai routes/api.php dari install:api, kosongkan file tersebut atau hapus parameter api: dari withRouting() agar tidak ada route ganda.
Keputusan bisnis: iuran kini bisa dibayar sebagian dan memiliki denda keterlambatan. Bentuk data V1 tidak bisa menampungnya tanpa mengubah makna jumlah.
// V1 (tetap dipertahankan)
{
"id": 812, "periode": "2026-10", "jumlah": 50000,
"lunas": false, "dibayar_pada": null
}
// V2
{
"id": 812, "periode": "2026-10",
"tagihan": { "pokok": 50000, "denda": 5000, "total": 55000 },
"terbayar": 20000,
"sisa": 35000,
"status": "sebagian",
"pembayaran": [ { "jumlah": 20000, "dibayar_pada": "2026-10-05T09:12:00+07:00" } ]
}
Resource V1 tetap menghasilkan bentuk lama dari model yang sudah berkembang:
// app/Http/Resources/V1/IuranResource.php
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'periode' => $this->periode,
'jumlah' => $this->pokok, // V1: jumlah = pokok (tanpa denda)
'lunas' => $this->status === StatusIuran::Lunas, // V1 hanya mengenal lunas/belum
'dibayar_pada' => $this->status === StatusIuran::Lunas ? $this->lunas_pada?->toIso8601String() : null,
];
}
// app/Http/Resources/V2/IuranResource.php
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'periode' => $this->periode,
'tagihan' => ['pokok' => $this->pokok, 'denda' => $this->denda, 'total' => $this->total_tagihan],
'terbayar' => $this->terbayar,
'sisa' => $this->sisa,
'status' => $this->status->value, // belum | sebagian | lunas
'pembayaran' => PembayaranResource::collection($this->whenLoaded('pembayaran')),
];
}
Kedua controller memakai service dan query yang sama:
// app/Http/Controllers/Api/V2/IuranController.php
public function index(Request $request, IuranQuery $query)
{
return V2\IuranResource::collection(
$query->untuk($request->user(), $request->validate(IuranQuery::rules()))
->with('pembayaran')
->cursorPaginate(25)
);
}
// app/Http/Controllers/Api/V1/IuranController.php
public function index(Request $request, IuranQuery $query)
{
return V1\IuranResource::collection(
$query->untuk($request->user(), $request->validate(IuranQuery::rules()))
->paginate(15) // V1 sejak awal memakai paginate; jangan ubah
);
}
Hindari membuat V2\IuranResource extends V1\IuranResource. Pewarisan antar versi membuat perubahan di V1 tanpa sengaja mengubah V2, dan sebaliknya. Lebih aman bila setiap versi berdiri sendiri, berbagi logika lewat service atau helper yang eksplisit.
Tidak semua endpoint perlu disalin ke V2. Untuk endpoint yang identik, arahkan route V2 ke controller V1:
// routes/api/v2.php
use App\Http\Controllers\Api\{V1, V2};
Route::middleware('auth:sanctum')->group(function () {
// Berubah di V2
Route::get('iuran', [V2\IuranController::class, 'index'])->name('iuran.index');
Route::post('iuran/{iuran}/pembayaran', [V2\PembayaranController::class, 'store'])->name('iuran.pembayaran.store');
// Tidak berubah: pakai implementasi V1
Route::apiResource('pengumuman', V1\PengumumanController::class)->parameters(['pengumuman' => 'pengumuman']);
Route::get('me', V1\MeController::class)->name('me');
});
Bila suatu saat endpoint tersebut perlu berubah di V2, buat controller V2-nya dan ganti route di file v2.php saja.
Middleware ini menandai versi pada request (untuk log) dan memberi tahu klien bila versi yang dipakai sudah usang.
// app/Http/Middleware/ApiVersion.php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\Response;
class ApiVersion
{
public function handle(Request $request, Closure $next, string $versi): Response
{
$request->attributes->set('api_version', $versi);
Log::withContext(['api_version' => $versi, 'client_version' => $request->header('X-Client-Version')]);
$response = $next($request);
$response->headers->set('X-Api-Version', $versi);
$info = config("api.versions.{$versi}");
if ($info['deprecated_at'] ?? null) {
// RFC 9745: Deprecation memakai format tanggal "@<unix-timestamp>"
$response->headers->set('Deprecation', '@'.strtotime($info['deprecated_at']));
$response->headers->set('Link', '<'.url($info['docs']).'>; rel="deprecation"', false);
}
if ($info['sunset_at'] ?? null) {
// RFC 8594: Sunset memakai format tanggal HTTP
$response->headers->set('Sunset', gmdate('D, d M Y H:i:s \G\M\T', strtotime($info['sunset_at'])));
}
return $response;
}
}
// config/api.php
return [
'versions' => [
'v1' => [
'deprecated_at' => '2026-11-01',
'sunset_at' => '2027-05-01',
'docs' => '/docs/api/migrasi-v1-ke-v2',
],
'v2' => [
'deprecated_at' => null,
'sunset_at' => null,
],
],
// Versi aplikasi mobile minimum yang masih diizinkan
'min_client_version' => env('API_MIN_CLIENT_VERSION', '2.3.0'),
];
// bootstrap/app.php
$middleware->alias([
'api.version' => \App\Http\Middleware\ApiVersion::class,
'client.min' => \App\Http\Middleware\MinimumClientVersion::class, // Langkah 7
'api.usage' => \App\Http\Middleware\CatatPemakaianApi::class, // Langkah 8
]);
Klien yang baik (termasuk aplikasi Anda sendiri) bisa membaca header Deprecation dan Sunset lalu menampilkan pesan "Silakan perbarui aplikasi" jauh sebelum versi lama dimatikan.
Aplikasi mobile mengirim versinya di setiap request:
X-Client-Version: 2.1.4
X-Client-Platform: android
// app/Http/Middleware/MinimumClientVersion.php
public function handle(Request $request, Closure $next): Response
{
$versi = $request->header('X-Client-Version');
// Hanya berlaku untuk aplikasi mobile; PWA dan integrasi tidak mengirim header ini
if ($versi && version_compare($versi, config('api.min_client_version'), '<')) {
return response()->json([
'message' => 'Versi aplikasi Anda sudah tidak didukung. Silakan perbarui aplikasi.',
'code' => 'client_update_required',
'minimum' => config('api.min_client_version'),
], 426); // 426 Upgrade Required
}
return $next($request);
}
Aplikasi menangani kode client_update_required dengan menampilkan layar wajib perbarui yang mengarah ke toko aplikasi. Gunakan mekanisme ini dengan hemat; menaikkan versi minimum berarti memaksa semua pengguna lama memperbarui.
Sebelum mematikan V1, Anda perlu tahu siapa yang masih memakainya.
// app/Http/Middleware/CatatPemakaianApi.php
public function handle(Request $request, Closure $next): Response
{
return $next($request);
}
public function terminate(Request $request, Response $response): void
{
$versi = $request->attributes->get('api_version');
if (! $versi) {
return;
}
$kunci = sprintf('api:pemakaian:%s:%s:%s',
now()->format('Y-m-d'),
$versi,
$request->header('X-Client-Version', 'tanpa-versi'),
);
Cache::increment($kunci); // ringan; direkap harian oleh scheduler
}
Middleware dengan method terminate() berjalan setelah respons dikirim ke klien, sehingga tidak menambah waktu respons. Rekap angka harian ini ke tabel atau sistem pemantauan, lalu tampilkan grafik "request V1 per hari". Matikan V1 hanya setelah angkanya mendekati nol atau tanggal sunset sudah lewat dan pengguna telah diberi tahu.
Setelah tanggal sunset:
// routes/api/v1.php (setelah sunset)
Route::any('{any}', fn () => response()->json([
'message' => 'API v1 sudah tidak tersedia. Gunakan /api/v2 atau perbarui aplikasi Anda.',
'code' => 'api_version_retired',
'docs' => url('/docs/api/migrasi-v1-ke-v2'),
], 410))->where('any', '.*');
Status 410 Gone memberi tahu klien bahwa sumber daya sengaja dihapus secara permanen, bukan error sementara.
Urutan yang disarankan:
deprecated_at; kirim header Deprecation; umumkan ke pengguna integrasi.sunset_at, ganti route V1 dengan respons 410.Setiap versi punya test kontrak sendiri. Test V1 tidak boleh diubah selama V1 masih hidup; bila test V1 gagal setelah perubahan kode, berarti Anda tanpa sengaja merusak klien lama.
// tests/Feature/Api/V1/IuranContractTest.php
use Illuminate\Testing\Fluent\AssertableJson;
use Laravel\Sanctum\Sanctum;
it('v1: bentuk iuran tetap sama walaupun model berubah', function () {
$warga = wargaDenganIuran(pokok: 50000, denda: 5000, terbayar: 20000);
Sanctum::actingAs($warga);
$this->getJson('/api/v1/iuran')
->assertOk()
->assertHeader('X-Api-Version', 'v1')
->assertHeader('Sunset')
->assertJson(fn (AssertableJson $json) => $json
->has('data.0', fn ($i) => $i
->where('jumlah', 50000) // tetap pokok, tanpa denda
->where('lunas', false)
->has('id')->has('periode')->has('dibayar_pada'))
->etc());
});
// tests/Feature/Api/V2/IuranContractTest.php
it('v2: menampilkan tagihan, terbayar, dan sisa', function () {
$warga = wargaDenganIuran(pokok: 50000, denda: 5000, terbayar: 20000);
Sanctum::actingAs($warga);
$this->getJson('/api/v2/iuran')
->assertOk()
->assertHeaderMissing('Deprecation')
->assertJsonPath('data.0.tagihan.total', 55000)
->assertJsonPath('data.0.sisa', 35000)
->assertJsonPath('data.0.status', 'sebagian');
});
it('menolak aplikasi di bawah versi minimum dengan 426', function () {
config(['api.min_client_version' => '2.3.0']);
Sanctum::actingAs(User::factory()->create());
$this->withHeader('X-Client-Version', '2.1.0')
->getJson('/api/v2/me')
->assertStatus(426)
->assertJsonPath('code', 'client_update_required');
});
wargaDenganIuran() adalah helper test yang membuat pengguna, keluarga, dan iuran dengan nilai tertentu (didefinisikan di tests/Pest.php).
Hasilkan juga dokumentasi terpisah per versi. Scribe dan Scramble bisa dikonfigurasi untuk mengelompokkan route berdasarkan prefiks api/v1/* dan api/v2/* (lihat artikel Membuat Dokumentasi API dan Panduan Instalasi).
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Route V1 dan V2 bentrok nama | Prefiks nama route sama | Gunakan ->name("api.{$versi}.") per versi |
| Route terdaftar dua kali | routes/api.php bawaan masih dimuat |
Hapus parameter api: dari withRouting() atau kosongkan file tersebut |
| Test V1 gagal setelah mengubah model | Resource V1 membaca kolom yang berubah | Petakan ulang di Resource V1 agar bentuk lama tetap terjaga |
| Perubahan di V1 ikut mengubah V2 | Resource V2 mewarisi V1 | Pisahkan; bagi logika lewat helper/service |
Header Sunset tidak terbaca di browser |
CORS tidak mengekspos header | Tambahkan ke exposed_headers di config/cors.php |
| Klien lama crash karena nilai enum baru | Klien tidak menangani nilai tak dikenal | Dokumentasikan aturan "abaikan nilai tak dikenal"; uji aplikasi dengan nilai baru sebelum rilis |
| Tidak tahu kapan aman mematikan V1 | Tidak ada data pemakaian | Catat pemakaian per versi dan versi klien |
Keamanan
Performa
terminate() dan dengan counter cache, bukan query per request.Maintainability
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Laravel Sanctum | 4.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Laravel Sanctum: Cara Mengamankan API untuk Aplikasi Web dan Progressive Web App
Berikutnya
Cara Mengintegrasikan Laravel dengan API Eksternal Menggunakan HTTP Client
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk