API entegrasyonu sürecinde karşınıza çıkabilecek sessiz değişimlerin farkında olmalısınız. Bu yazıda, böyle bir durumda karşılaştığım bir deneyimi paylaşacağım.
Cuma akşamı saat 11’de uyarılar gelmeye başladı. Siparişler başarısız oluyordu. Laptopumu açtığımda, 23 müşteri hata ekranıyla karşılaşmış ve sepete ekledikleri ürünleri bırakmıştı. İki saat boyunca kendi kodumuzu eleştirdim. Yapılan son dağıtımları kontrol ettim ve iki kez geri aldım.
Bizim tarafımızda hiçbir şey değişmemişti. Sonra Stripe’dan gelen ham API yanıtına baktım. Sekiz aydır güvenerek kullandığımız bir alan aniden yok olmuştu. Hiçbir duyuru, erteleme uyarısı veya 500 hatası yoktu. Yanıt, 200 OK olarak geldi ve geçerli bir JSON gövdesine sahipti. Ancak gövdede beklediğimizden daha az alan vardı.
Stripe, belirli durumlarda yanıtlarının bir kısmını sessizce yeniden yapılandırmıştı. Onlar için “non-breaking change” kabul edilen bu durum, bizim için sorun oluşturmuştu.
Sessiz API Değişikliklerinin Tehdidi
Herhangi bir üçüncü taraf API ile entegrasyon yapıyorsanız, bu riskle şu anda karşı karşıyasınız. Stripe, Shopify, Twilio gibi platformlar yanıt şemalarını sürekli geliştiriyor. Her alan düzeyindeki değişikliği versiyonlamıyorlar. Bir alan kayboluyor. Bir dizi bir tamsayıya dönüşüyor. Daha önce zorunlu olan bir alan artık isteğe bağlı hale geliyor. PHP, kaybolan dizi anahtarını sessizce null olarak ele alıyor ve uygulamanız yanlış verileri şikayet etmeden işliyor.
Testleriniz bu durumu yakalayamaz çünkü testleriniz aylar önce yazdığınız statik verileri kullanıyor. Standart izleme de kaydedemiyor çünkü HTTP durum kodu hala 200.
php-sentinel ile Tanışın
Bunu çözmek için açık kaynak bir araç geliştirdim. Adı php-sentinel.
Bu araç, uygulamanız ile aldığınız HTTP yanıtları arasında pasif olarak yer alır. Üretim ortamında geçen yanıtları izler ve bunların nasıl görünmesi gerektiğini öğrenir. Yeterli örnek gördüğünde bu bilgiyi bir temel şemaya dönüştürür.
Bundan sonrasında her yeni yanıt bu temel ile sessizce karşılaştırılır. Eğer yapısı değişirse, hemen bildirim alırsınız, böylece 23 siparişin başarısız olmasını beklemezsiniz.
Guzzle ile Entegrasyon
İşte Guzzle ile entegrasyon örneği:
use Sentinel\Middleware\SchemaWatcher;
use Sentinel\Sentinel;
use Sentinel\Store\FileSchemaStore;$sentinel = Sentinel::create()
->withStore(new FileSchemaStore(storage_path('sentinel')))
->withSampleThreshold(20)
->withDispatcher($dispatcher)
->build();$reporter = new DriftReporter($dispatcher);
$watcher = new SchemaWatcher($httpClient, $sentinel, $reporter);$response = $watcher->sendRequest($request);
Event::listen(SchemaDriftDetected::class, function ($event) {
$drift = $event->drift;Log::error("API schema drift detected", [
'endpoint' => $drift->endpoint,
'severity' => $drift->severity->value,
'changes' => array_map(fn($c) => $c->getDescription(), $drift->changes),
]);});Ne Tür Değişiklikleri Tespit Eder?
Drift dedektörü, JSON Şeması anlamını anlar ve şiddeti sınıflandırır (BREAKING, ADDITIVE veya ADVISORY):
- FieldRemoved: Her yanıtın içinde bulunan bir alan artık görünmüyor.
- NowNullable: Her zaman nesne veya dizi olarak gelen bir alan artık bazen null dönebilir.
- TypeChanged: Bir alanın tipi string’den tamsayıya veya nesneden diziye değişebilir.
- RequiredNowOptional: Kodunuzun güvendiği bir alan artık yalnızca bazen mevcut.
- EnumValueAdded / EnumValueRemoved: Üç değeri olan bir durum alanı artık dördüncü bir değere sahip.
Paketin Alınması
Kendi altyapımıza obsesif bir şekilde yaklaşırken, dış API’lerle olan sözleşmelerimizi sanki sonsuza dek sabitmiş gibi düşünüyoruz. Oysa durum böyle değil. Üretim ortamınızı bozacak bir sonraki sessiz güncellemeyi beklemeyi bırakın.
GitHub Deposu: malikad778/php-sentinel
Kurulum: composer require php-sentinel/sentinel
PHP 8.3+ ile, yerel Laravel ve Symfony desteğiyle geliştirilmiştir. MIT Lisanslı.
Geçmişte yaşadığınız sessiz API değişikliklerinden hangileri size sorun oluşturdu? Yorumlarınızı bekliyorum.
Kaynak: Orijinal Makale
