Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / API Versioning di Laravel: Str...
REST API, Integrasi & Automation

API Versioning di Laravel: Strategi Menjaga Kompatibilitas Saat Aplikasi Berkembang

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
13 min read
13 views

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.

Overview

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"},
  • field status diganti dari "lunas" menjadi "paid",
  • endpoint daftar iuran kini wajib parameter periode,
  • error validasi untuk tanggal diganti nama menjadi tanggal_bayar.

Hasil akhir:

  • pemahaman jelas perubahan mana yang merusak dan mana yang aman,
  • strategi versi lewat URL (/api/v1, /api/v2) dengan struktur kode yang rapi,
  • logika bisnis yang dipakai bersama oleh semua versi; perbedaan hanya di lapisan HTTP,
  • header Deprecation dan Sunset untuk versi lama,
  • pemantauan pemakaian per versi dan per versi aplikasi,
  • penolakan versi aplikasi yang terlalu lama dengan pesan yang jelas,
  • test kontrak untuk setiap versi.

Prerequisites

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.

Step-by-step Tutorial

Langkah 1: Bedakan Perubahan Aman dan Merusak

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.

Langkah 2: Pilih Strategi Versi

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.

Langkah 3: Struktur Kode per Versi

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.

Langkah 4: Contoh Perubahan dari V1 ke V2

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.

Langkah 5: Endpoint yang Tidak Berubah

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.

Langkah 6: Middleware Versi, Deprecation, dan Sunset

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.

Langkah 7: Paksa Pembaruan untuk Aplikasi yang Terlalu Lama

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.

Langkah 8: Pantau Pemakaian per Versi

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.

Langkah 9: Mematikan Versi Lama dengan Sopan

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:

  1. Rilis V2 dan aplikasi yang memakainya.
  2. Tandai V1 deprecated_at; kirim header Deprecation; umumkan ke pengguna integrasi.
  3. Pantau pemakaian V1.
  4. Naikkan versi aplikasi minimum bila perlu.
  5. Setelah sunset_at, ganti route V1 dengan respons 410.
  6. Setelah beberapa waktu, hapus kode V1.

Langkah 10: Test Kontrak per Versi

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).

Troubleshooting

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

Best Practices

Keamanan

  • Versi lama tetap menerima perbaikan keamanan selama masih hidup; jangan biarkan V1 tertinggal.
  • Kebijakan otorisasi dan validasi inti berada di service/Policy bersama, sehingga perbaikan berlaku di semua versi.
  • Matikan versi lama tepat waktu untuk mengurangi permukaan serangan.

Performa

  • Pencatatan pemakaian dilakukan di terminate() dan dengan counter cache, bukan query per request.
  • Endpoint yang tidak berubah memakai implementasi yang sama, bukan salinan.

Maintainability

  • Evolusi aditif terlebih dahulu; versi baru hanya untuk perubahan yang benar-benar merusak.
  • Hanya lapisan HTTP yang berbeda per versi; logika bisnis satu.
  • Test kontrak per versi yang tidak diubah selama versi hidup.
  • Jadwal deprecation dan sunset tertulis di konfigurasi dan diumumkan.
  • Panduan migrasi antar versi untuk pengguna integrasi.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Laravel Sanctum 4.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya