Nansen AI API için Şık bir PHP İstemcisi: nansen-php’ye Derinlemesine Bakış

Üçüncü parti API’leri entegre etmek genellikle tekrarlayıcı bir rutin haline gelebilir: aynı cURL şablonunu kopyalayıp yapıştırmak, JSON yanıtlarını manuel olarak çözümlemek ve her yeni projede hız sınırı ile hata işleme mantığını yeniden oluşturmak zorunda kalabilirsiniz. Eğer kripto para verileri ile çalışıyorsanız ve Nansen AI API’sinden yararlanıyorsanız, Igor Sazonov (tigusigalpa) tarafından geliştirilmiş olan nansen-php isimli kütüphane bu yükü hafifletmeyi vaat ediyor.

Bu makalede, tigusigalpa/nansen-php deposuna kapsamlı bir bakış atacağız. Mimarisini inceleyecek, temel özelliklerini vurgulayacak ve neden PHP geliştiricilerinin, özellikle Laravel ekosisteminde çalışanların dikkatini hak ettiğini anlayacağız.

nansen-php Nedir?

nansen-php, Nansen AI API’si için özel olarak tasarlanmış, framework bağımsız bir PHP 8.1+ istemcisidir. Geliştiricilere istek yapmak için şık, akıcı (zincirleme) bir arayüz sunar, güçlü biçimlendirilmiş Veri Taşıma Nesneleri (DTO’lar) döner, otomatik olarak hız limitlerini yönetir ve Laravel çerçevesi (10’dan 13’e kadar) için birinci sınıf destek sunar.

Kütüphanenin temel amacı, HTTP istekleri arka planında tüm sıkıcı kodları gizleyerek, kodunuzun neredeyse doğal bir dil cümlesi gibi okunmasını sağlamaktır.

Temel Özellikler ve Mimari Kararlar

Kütüphanenin kaynak kodunu inceledikten sonra, Nansen AI entegrasyonu için mükemmel bir araç haline getiren birkaç güçlü mimari seçim dikkat çekmektedir.

1. İkna Edici Akıcı API

Parametrelerin dizilerini manuel olarak oluşturmak ve bunları bir HTTP istemcisine geçirmek yerine, nansen-php, Builder desenini benimsemektedir. RequestBuilder sınıfı adım adım sorgu oluşturmanıza olanak tanır:

use Tigusigalpa\Nansen\NansenClient;

$client = NansenClient::create(['api_key' => 'YOUR_API_KEY']);

$netflows = $client
    ->smartMoney()
    ->netflows()
    ->chains(['ethereum'])
    ->limit(10)
    ->get();

Her modifikatör metodu (chains(), filters(), orderBy(), limit(), offset(), page()) mevcut builder örneğini kopyalar ve yeni bir nesne döner. Bu, değişmezliği sağlar ve temel sorguları istenmeyen yan etkiler olmadan yeniden kullanmanıza olanak tanır.

2. Sıkı Türlendirme ve Veri Taşıma Nesneleri (DTO’lar)

PHP’de dış API’lerle çalışırken karşılaşılan en büyük zorluklardan biri, gevşek yapılandırılmış, ilişkisel dizilerle uğraşmaktır. nansen-php, bu sorunu, türlendirilmiş nesneler döndürerek çözer.

Tüm yanıtlar bir temel Dto sınıfından türetilir. Bu, listelerin gerçek koleksiyonlar olarak döndüğü ve özellik erişiminin dizi anahtarları yerine nesne özellikleri aracılığıyla yapıldığı anlamına gelir.

Her DTO, aynı zamanda orijinal, dokunulmamış API yanıtını ->raw özelliğinde saklar. Eğer Nansen yarın API yanıtlarına yeni bir alan eklerse ve kütüphane henüz güncellenmemişse, bu veriyi hemen erişebilirsiniz:

// Yeni, belgelenmemiş alanlara erişmek uygulamanızı geleceğe dönük hale getirir
$brandNewField = $netflows->raw['data'][0]['brand_new_field'] ?? null;

Bu, asla kütüphane sürümünün gerisinde kalmadan veri kaybetmemenizi garanti eder.

3. Otomatik Hız Sınırı Yönetimi ve Yeniden Deneme Mantığı

Gelişmiş API’lerle çalışmak, genellikle 429 Too Many Requests hataları ile karşılaşmayı içerir. Http isim alanındaki Client sınıfı, bu senaryolardan tam anlamıyla sorumludur.

Bir 429 durumu alındığında, istemci otomatik olarak Retry-After, X-RateLimit-Remaining veya RateLimit-Remaining başlıklarını çıkartır. Ardından, gerekli süre boyunca scriptin yürütülmesini durdurur ve isteği otomatik olarak yeniden dener.

Sunucu tarafı hataları (HTTP durumları >= 500) için ise, kütüphane bir üstel geri çekilme algoritması uygular. Yeniden deneme girişimlerinin sayısı ve temel gecikme kolayca yapılandırılabilir.

4. Açık İstisna Hiyerarşisi

Kütüphane basitçe genel istisnalar fırlatmakla kalmaz. Temel bir ApiException‘dan türeyen yapılandırılmış bir hiyerarşi sunar:

• RateLimitException: Hız sınırı aşıldığında ve tüm yeniden deneme girişimlerinin tükenmesi halinde fırlatılır. Kullanışlı retryAfter() ve remaining() yöntemlerini sağlar.

• UnauthorizedException: 401 durumları için fırlatılır, genellikle geçersiz veya süresi dolmuş bir API anahtarını belirtir.

• NotFoundException: 404 durumları için fırlatılır, bir kaynak veya adres bulunamadığında devreye girer.

Bu hiyerarşi, geliştiricilerin belirli hataları kolayca yakalayıp, uygulamalarında zarif bir şekilde işleyebilmelerini sağlar.

5. HTTP İstemci Bağımsızlığı (PSR-18)

Varsayılan olarak, nansen-php Guzzle’ı (guzzlehttp/guzzle) kullanmaktadır. Bununla birlikte, kütüphane PSR-18 standardına tam uygunluk gösterir. Herhangi bir PSR-18 uyumlu HTTP istemcisini, yapıcıya geçirerek veya Laravel hizmet konteynerine bağlayarak entegre edebilirsiniz. Bu, özel middleware, günlükleme veya belirli SSL yapılandırmalarına sahip bir istemci kullanmanız gerektiğinde özellikle yararlıdır.

6. Birinci Sınıf Laravel Entegrasyonu

Kütüphane, temelde framework bağımsız olsa da, Laravel kullanıcıları için sorunsuz bir geliştirici deneyimi sunar. Paket, otomatik olarak NansenServiceProvider sunucusunu keşfederek NansenClient‘ı config/nansen.php üzerinden yapılandırır.

Ayrıca, size son derece özlü kod yazma imkanı sunan bir Nansen facade’ı da sağlar:

use Tigusigalpa\Nansen\Laravel\Facades\Nansen;

$balances = Nansen::profiler()
    ->addressBalance('0x1234...')
    ->get();

Desteklenen Uç Noktalar

1.0.0 sürümünden itibaren, kütüphane Nansen AI uç noktalarının temel ve en çok talep edilenlerini kapsamaktadır:

Her uç nokta aynı modifikatör setini paylaştığı için, bir uç noktayı sorgulama yöntemini öğrendiğinizde, hepsini nasıl sorgulayacağınızı hemen bilirsiniz.

Kod Kalitesi ve Test

Depo analizi, yüksek bir mühendislik kültürü standardını ortaya koymaktadır:

• PHP 8.1+ Özellikleri: Kod tabanı, readonly özellikler, match ifadeleri ve sıkı türlendirme gibi modern PHP özelliklerini aktif olarak kullanmaktadır.

• Test: tests dizininin varlığı ve bir phpunit.xml yapılandırma dosyası, kodun testlerle kaplı olduğunu gösterir. README’ye göre, test suite’i bir taklit HTTP istemcisine karşı çalışır, bu da gerçek bir API anahtarına veya ağ erişimine ihtiyaç olmadığı anlamına gelir.

• Standartlar: Tüm dosyalar arasında declare(strict_types=1); kullanımı tutarlıdır.

Sonuç

tigusigalpa/nansen-php deposu, modern bir PHP API SDK’sının nasıl olması gerektiğine dair örnek bir modeldir. Yazar, yalnızca cURL isteklerini sınıflara sarak değil, gerçek geliştirici sorunlarını çözen düşünceli bir mimari oluşturmuştur: yanıt türlendirme, hız sınırı yönetimi ve kod okunabilirliği.

İster bir karmaşık kripto analiz platformu geliştirin, ister cüzdanları izlemek için küçük, bağımsız bir PHP scripti yazın, bu kütüphane size saatlerce boilerplate kod yazmaktan kurtaracak ve kod tabanınızı daha temiz ve güvenilir hale getirecektir.

Bu deponun MIT lisansına sahip olduğunu ve katkılara açık olduğunu unutmayın. Eğer Nansen API’si ile çalışıyorsanız, tigusigalpa/nansen-php‘yi composer.json dosyanıza eklemeye değer.

Referanslar