Uygulamaları Bozmayı Durdurun: Laravel’de API Sürümleme

Mobil İstemci Lag Tuzağı

Smart Tech Devs’de SaaS API’leri oluşturduğunuzda, web frontend’iniz üzerinde tam kontrolünüz vardır. API yanıt yapısını değiştirdiğinizde, aynı anda bir frontend güncellemesi dağıtmanız yeterlidir. Ancak bir Mobil Uygulama başlattığınızda veya harici üçüncü taraf entegrasyonlarına izin verdiğinizde, bu kontrol kaybolur.

Bir veritabanı sütununu user_name‘dan full_name‘a yeniden adlandırdığınızı düşünün. Güncellenmiş API’nizi dağıttınız. Anında, 15,000 mobil uygulama kullanıcısı kritik bir çökme ile karşılaşıyor. Neden? Çünkü Apple’ın App Store’u mobil güncellemenizi onaylamak için 48 saat alıyor ve o zaman bile, binlerce kullanıcı aylarca telefonlarını güncellemeyecek. Eski uygulama hala user_name bekliyor. Kurumsal platformları eski kullanıcıları dışlamadan ölçeklendirmek için, sıkı bir API Versiyonlama uygulamanız gerekir.

Çözüm: Header Tabanlı API Dönüşümü

Tamamen kopyalanmış denetleyiciler oluşturmak yerine (örneğin, Controllers/V1 ve Controllers/V2 gibi, bu da büyük kod bozulmasına yol açar), modern sistemler, Stripe gibi, merkezi bir dönüşüm katmanı kullanır.

Müşteri, HTTP Header aracılığıyla açıkça bir API versiyonu talep eder (örneğin, Api-Version: 2024-05-12). Backend, her zaman en yeni, en modern veritabanı şeması ve denetleyici mantığı ile isteği işleme alır. Ancak JSON yanıtı gönderilmeden hemen önce, bir middleware bunu engeller ve veriyi eski istemcinin beklediği tam formata geri döndürmek için bir dizi “Dönüşüm Matrisinden” geçirir.

Adım 1: Versiyon Middleware’ini Mimarlama

Yanıtı yakalayan, talep edilen versiyonu kontrol eden ve yükü dinamik olarak manipüle eden bir Laravel middleware’i oluşturuyoruz.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class EnforceApiVersioning
{
    public function handle(Request $request, Closure $next)
    {
        // 1. İstemci başlıklarından istenen versiyonu yakalayın
        $requestedVersion = $request->header('Api-Version', '2024-01-01'); // En eski versiyona geri döner

        // 2. Modern denetleyici normalde mantığını çalıştırmasına izin verin
        $response = $next($request);

        // 3. ✅ KURUMSAL PATRON: Yanıtın Düşürülmesi
        // Sadece JSON yanıtlarını değiştirin
        if (str_contains($response->headers->get('Content-Type'), 'application/json')) {
            $data = json_decode($response->getContent(), true);

            // Eğer istemci eskiyse, yeni şemayı eski şemaya geri döndürüyoruz
            if ($requestedVersion === '2024-01-01') {
                $data = $this->downgradeToV1($data);
            }

            $response->setContent(json_encode($data));
        }

        return $response;
    }

    private function downgradeToV1(array $data): array
    {
        // Modern 'full_name'i eski 'user_name' formatına dönüştür
        if (isset($data['full_name'])) {
            $data['user_name'] = $data['full_name'];
            unset($data['full_name']);
        }
        return $data;
    }
}

Adım 2: Mobil İstemciyi Güvenceye Alma

Mobil mühendisleriniz veya harici tüketiciler artık HTTP istemcilerinde karşı karşıya oldukları API versiyonunu sabit kodlayabilirler.

// Swift / Mobil HTTP İstemcisi
var request = URLRequest(url: URL(string: "https://api.smarttechdevs.in/users/1")!)
request.addValue("2024-01-01", forHTTPHeaderField: "Api-Version")
// Mobil uygulama her zaman 'user_name' alacak, backend gelişse bile!

Mühendislik ROI’si

Header tabanlı yanıt düşürmeye geçerek, veritabanı evrimini mobil uygulama yayın döngülerinden ayırırsınız. Backend ekibiniz, eski harici istemcileri kırmaktan endişe duymadan, temel mimariyi acımasızca yeniden yapılandırabilir ve optimize edebilir. Bu, sıfır kesinti süresiyle yapısal göçlere ve tüm cihazlarda kusursuz bir kullanıcı deneyimine yol açar.