API’nizi Bozmaktan Kaçının: Laravel’de URL Versiyonlamasını Ustaca Yapın

Kırılma Değişiminin Kabusu

Smart Tech Devs’de B2B SaaS platformu geliştirirken, API’niz müşterilerinizle sağlam bir sözleşmedir. Bir müşterinin API’nizi dahili ERP sistemine entegre ettiğini düşünün. Bir gün, user yükünü yeniden yapılandırmaya karar veriyorsunuz ve first_name ve last_name alanlarını tek bir full_name alanına dönüştürüyorsunuz. Güncellemeyi dağıtıyorsunuz ve hemen müşterinizin ERP entegrasyonu çöküyor. İş akışları duruyor ve güvenlerini kaybediyorsunuz.

Kurumsal yazılımda, dış müşterilerinizi (ve hatta eski sürümlere sahip mobil uygulamalarınızı) backend’inizi güncellediğiniz anda kodlarını güncellemeye zorlayamazsınız. Yenilik yaparken eski veri yapılarını desteklemelisiniz. Çözüm API Versioning‘dir.

URL Tabanlı Versiyonlamayı Mühendislik

API’leri versiyonlamanın birkaç yolu vardır (örneğin, Accept başlıkları kullanmak gibi), ancak URL tabanlı versiyonlama (örneğin, /api/v1/ ve /api/v2/) B2B platformları için en açık, önbellek dostu ve geliştirici dostu yaklaşım olarak öne çıkmaktadır.

Aşama 1: Rota Ayrımı

Laravel 11+ ile rotalarımızı versiyonları net bir şekilde ayıracak şekilde yapılandırıyoruz. Tüm her şeyi tek bir api.php dosyasına doldurmak yerine, bootstrap/app.php veya rota hizmet sağlayıcısında belirli dosyaları haritalıyoruz.

// routes/api_v1.php
use App\Http\Controllers\Api\V1\UserController;

Route::prefix('v1')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

// routes/api_v2.php
use App\Http\Controllers\Api\V2\UserController;

Route::prefix('v2')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

Aşama 2: Dönüşüm İçin API Kaynaklarından Yararlanma

Versiyonlama konusundaki en büyük hata, her sürüm için tüm veritabanı mantığını ve Eloquent modellerini kopyalamaktır. İş mantığını kopyalamaktan kaçının. Veritabanı aynı kalır; yalnızca verinin sunumu değişir.

Bu sunum katmanını yalnızca Laravel API Kaynakları aracılığıyla yönetiyoruz.

// App\Http\Resources\V1\UserResource.php
namespace App\Http\Resources\V1;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        // V1 müşterileri ayrı ad alanları bekler
        return [
            'id' => $this->id,
            'first_name' => $this->first_name,
            'last_name' => $this->last_name,
            'email' => $this->email,
        ];
    }
}

// App\Http\Resources\V2\UserResource.php
namespace App\Http\Resources\V2;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        // V2 müşterileri yeni optimize edilmiş, birlikteliği sağlanmış yükü alır
        return [
            'id' => $this->id,
            'full_name' => $this->first_name . ' ' . $this->last_name,
            'email' => $this->email,
            'status' => $this->is_active ? 'active' : 'inactive', // Yeni V2 özelliği
        ];
    }
}

Aşama 3: Kontrolör Katmanı

Kontrolörleriniz, standart Repository veya Servislerinizi kullanarak verileri alır ve ardından bu verileri sürüme özel Kaynağa aktarır.

// App\Http\Controllers\Api\V2\UserController.php
namespace App\Http\Controllers\Api\V2;

use App\Http\Controllers\Controller;
use App\Models\User;
use App\Http\Resources\V2\UserResource;

class UserController extends Controller
{
    public function index()
    {
        // Sorgu mantığı V1 ile aynı
        $users = User::active()->paginate(50);
        
        // Ancak dönüşüm tamamen V2'ye özgüdür
        return UserResource::collection($users);
    }
}

Sonuç

API Versioning bir kenara atılamaz; bu, kalıcı bir B2B SaaS için temel bir gerekliliktir. Rotalarınızı ayırarak ve yük dönüşümlerini sürüme özgü API Kaynakları içine izole ederek, Laravel backend’inizi sürekli olarak geliştirebilir ve müşterilerinizin bağımlı olduğu entegrasyonları asla bozmazsınız.