IP ve Ağ Verisi API'leri Nasıl Entegre Edilir?
API, bir yazılımın başka bir servisten tanımlı istek ve yanıt biçimleriyle veri almasını sağlar. IP adresi, ASN, yaklaşık konum veya DNS verisi sunan API'leri entegre ederken yalnız HTTP isteğini göndermek yetmez. Yanıt eksik olabilir, veri değişebilir veya belirli bir sürede kabul edilen istek sayısı sınırına ulaşılabilir. Sorgulanan IP adresi de kullanım bağlamına göre gizlilik açısından hassas olabilir.
Uygulamanın ihtiyaç duyduğu veriyi önce bir iç sözleşmeyle tanımlayın. Ardından dış ağ verisi sağlayıcısının yanıtını bu sözleşmeye uyarlayan ayrı bir katman kullanın. Böylece doğrulama, hata yönetimi, önbellek, kayıt ve geri alma davranışları sağlayıcının tekil özelliklerinden bağımsız olarak yönetilir.
İç Veri Sözleşmesinde Girdi ve Çıktı Alanları
Ağ verisi sağlayıcısı seçmeden önce uygulamanın gerçekten hangi alanlara ihtiyaç duyduğu yazılı hale getirilmelidir. Örneğin bir erişim kararında yalnız ASN ve ülke kodu yeterliyken, kullanıcı arayüzünde operatör adı veya yaklaşık şehir bilgisi de gerekebilir. Gereksiz alanları sözleşmeye almak hem ağ verisi sağlayıcısına bağımlılığı hem de saklanan veri miktarını artırır.
Girdi Sözleşmesi
Her işlem için kabul edilen girdi türü, biçimi ve uzunluk sınırı ayrı tanımlanmalıdır. Bir IP adresi sorgusu yalnız geçerli IPv4 veya IPv6 adresi; DNS sorgusu ise geçerli alan adı ile izin verilen kayıt türünü kabul etmelidir. Kullanıcının sağladığı metin, ağ verisi sağlayıcısının URL'sine kontrolsüz biçimde eklenmemeli ve hedef servis adresini değiştirememelidir.
Girdi sözleşmesi ayrıca özel, loopback (geri döngü), link-local (yerel bağlantı), multicast (çoklu yayın) ve ayrılmış adreslerin nasıl ele alınacağını belirtmelidir. Bu adresler dış ağ verisi sağlayıcılarında anlamlı sonuç üretmeyebilir; bazı kullanım senaryolarında reddedilmeleri, bazılarında ise dış isteğe çıkmadan yerel olarak sınıflandırılmaları daha doğrudur.
Çıktı Sözleşmesi
İç model, sağlayıcının yanıtındaki veri alanlarının adlarını kopyalamak yerine uygulamanın anlamlandırdığı alanları kullanmalıdır. ASN, ağ bloğu, kuruluş, ülke, bölge, yaklaşık koordinat, DNS kayıtları, kaynak adı ve veri zamanı gibi alanların türü, boş olabilme durumu ve anlamı açıkça tanımlanmalıdır.
Boş, bilinmeyen ve uygulanamaz değerler aynı şey değildir. Sağlayıcının bir alanı göndermemesi, değerin bilinmediğini bildirmesi veya alanın sorgu türüne uygulanamaması ayrı durumlar olarak tutulmalıdır. Gönderilmeyen bir alanın neden eksik olduğu, sağlayıcının açıklaması olmadan tahmin edilmemelidir. Aksi halde arayüz, karar motoru ve raporlama katmanı eksik veriyi yanlış bir kesinlikle yorumlayabilir.
Yanıta veri kaynağı, sorgu zamanı, varsa sağlayıcının veri güncelleme zamanı ve iç şema sürümü eklemek sonradan yapılacak incelemeyi kolaylaştırır. IP adresi, ASN ve alan adı kayıt bilgilerini sunan RDAP gibi protokoller, JSON biçiminde yapılandırılmış yanıtlar verir. Uygulama ihtiyaç duyduğu alanların türünü ve anlamını doğrulamalıdır. RDAP yanıtına eklenmiş tanınmayan bir alan tek başına yanıtın bozuk olduğunu göstermez; uygulamanın kullanmadığı alanlar yok sayılabilir.
IP Adresi, Alan Adı ve DNS Girdilerinin Doğrulanması
IP adresi API entegrasyonunda doğrulama, yalnız nokta veya iki nokta üst üste karakterlerini kontrol etmek değildir. Adres, güvenilir bir IP ayrıştırıcısıyla çözümlenmeli; normalleştirilmiş biçim elde edilmeli ve uygulamanın izin verdiği adres kapsamına göre sınıflandırılmalıdır. Metin olarak farklı görünen eşdeğer IPv6 adreslerinin aynı önbellek anahtarına dönüşmesi de bu aşamada sağlanır.
Alan adlarında Unicode gösterimi, ASCII uyumlu gösterim, sondaki nokta, etiket uzunlukları ve toplam uzunluk birlikte ele alınmalıdır. DNS kayıt türü serbest metin yerine izin listesiyle seçilmelidir. A ve AAAA sorguları alan adından IPv4 veya IPv6 adresi arar. Ters DNS sorgusunda ise uygulama IP adresini alabilir, ancak DNS'e gönderilen PTR sorgusunun adı IPv4 için in-addr.arpa, IPv6 için ip6.arpa altında oluşturulur. Bu dönüşümü API sağlayıcısının mı yoksa uygulamanın mı yaptığı doğrulanmalıdır.
Toplu sorgularda tek kaydın doğrulama hatası bütün işi belirsiz hale getirmemelidir. Her öğe için kabul, ret ve gerekçe kaydedilmeli; toplam öğe sayısı, eşzamanlılık ve istek başına boyut sınırı uygulanmalıdır.
HTTP İsteklerinde Zaman Aşımı, İstek Sınırı ve Hatalar
HTTP durum kodu, yanıtın yalnız bir bölümünü açıklar. Başarılı durum kodu dönen bir yanıtta beklenen alanlar eksik olabilir; hata durumunda ise ağ verisi sağlayıcısı JSON yerine HTML veya boş gövde gönderebilir. Uygulama HTTP durum kodunu, yanıt içindeki işlem sonucunu, içerik türünü, yanıt boyutunu ve şema doğrulamasını birlikte değerlendirmelidir. Örneğin HTTP 200 ile gelen bir DNS API yanıtı, kendi içinde DNS sorgusunun başarısız olduğunu bildirebilir.
Aşağıdaki ayrım, ağ verisi API'lerinde hata yönetimi için uygulama davranışını netleştirir.
| Durum | Uygulama Yorumu | Önerilen Davranış |
|---|---|---|
| Geçersiz girdi | İstek dış servise gönderilmeden reddedilebilir | Kullanıcıya alan bazlı hata verin ve yeniden denemeyin. |
| Kimlik doğrulama veya yetki hatası | Yapılandırma ya da yetki kapsamı sorunu olabilir | Gizli bilgiyi göstermeden işlemi durdurun ve sorumlu ekibe hata bildirimi gönderin. |
| İstek sayısı sınırı | Belirli bir sürede izin verilen istek sayısı veya hesap kotası aşılmış olabilir | Sağlayıcının bekleme bilgisini ve kotanın yenilenme koşulunu kontrol edin; koşullar uygunsa sınırlı sayıda yeniden deneyin. |
| Zaman aşımı veya bağlantı hatası | Geçici kesinti, yanlış hedef adresi veya sertifika doğrulama hatası gibi farklı nedenler olabilir | Hatayı sınıflandırın; yalnız yeniden denenebilir hatalarda ve işlemin tekrarı güvenliyse tekrar deneyin. |
| Sunucu hatası | Ağ verisi sağlayıcısı geçici olarak kullanılamıyor olabilir | Önbellekte uygun veri varsa kaynağını belirterek kullanın; aksi halde kontrollü hata döndürün. |
| Şema veya içerik hatası | Yanıt alınmış ancak sözleşmeye uymamıştır | Veriyi kullanmayın; örneği gizlilik sınırları içinde inceleme kuyruğuna alın. |
Bağlantı ve okuma zaman aşımı ayrı belirlenmeli, toplam istek süresi uygulamanın kabul ettiği yanıt süresini aşmamalıdır. Yanıt boyutu sınırlandırılmalı; yönlendirmeler kapatılmalı veya her adımda hedef yeniden doğrulanmalıdır. API isteklerinin gönderildiği sunucu adresi uygulama yapılandırmasından alınmalı, kullanıcı yalnız sorgu parametresini belirleyebilmelidir. Hedef sunucu, protokol ve port için izin listesi ile ağ çıkışı kısıtlamaları birlikte uygulanmalıdır. Bağlantıda kullanılacak IPv4 ve IPv6 adresleri de denetlenerek DNS yanıtı veya yönlendirme üzerinden izin verilmeyen hedeflere erişim önlenmelidir. Sorgulanan IP adresi ile bağlantı kurulan API sunucusunun adresi birbirine karıştırılmamalıdır.
Yeniden deneme kararı, hatanın geçici olup olmadığına ve isteğin tekrarlanmasının etkisine göre verilmelidir. Aynı isteğin tekrarı sunucuda amaçlanan sonucu değiştirmiyorsa işlem idempotent olarak adlandırılır; ancak her tekrar kotadan düşebilir veya ücretlendirilebilir. Özellikle POST ile yapılan toplu sorgularda, zaman aşımı önceki işlemin sunucuda çalışmadığını kanıtlamaz. Sağlayıcının tekrar deneme kuralları doğrulanmadan aynı işlem otomatik olarak gönderilmemelidir.
Yeniden denemeler hem istek başına hem uygulamanın toplam yükü açısından sınırlandırılmalıdır. Denemeler arasında artan bekleme süresine rastgele gecikme eklemek, çok sayıda istemcinin aynı anda yeniden istek göndermesini azaltır. Sağlayıcı Retry-After başlığı döndürürse bu değer saniye cinsinden bekleme süresi veya bir HTTP tarihi olabilir. Bu bekleme, toplam yanıt süresi bütçesini aşıyorsa aynı işlem içinde yeniden denemek yerine uygun önbellek verisi ya da açık bir hata sonucu kullanılmalıdır.
Art arda başarısız isteklerde yeni çağrıları bir süre durdurup daha sonra sınırlı denemelerle servisin düzelip düzelmediğini kontrol eden circuit breaker kullanılabilir. Bu mekanizma yeniden denemenin yerine geçen bir bekleme ayarı değildir; kullanılamayan servise sürekli yük gönderilmesini önler. Gizli API anahtarları sunucu tarafındaki güvenli yapılandırma deposunda tutulmalı, yenilenmeli ve günlüklerden çıkarılmalıdır.
Önbellek Süresi ve Veri Tazeliği
IP adresi, ASN, yaklaşık konum ve DNS verileri aynı hızda değişmez. Bu nedenle tek bir genel önbellek süresi yerine veri sınıfı, kullanım amacı ve eski veri kullanmanın olası sonucu birlikte değerlendirilmelidir. Örneğin ekran üzerinde bilgi göstermek için kabul edilebilir eskime, erişim politikası üreten bir karar için fazla uzun olabilir.
Önbellek anahtarı normalleştirilmiş girdi, sorgu türü, veri kümesi, iç şema sürümü ve gerekiyorsa ağ verisi sağlayıcısının kimliğini içermelidir. Başarılı sonuç, bulunamayan kayıt ve geçici hata aynı süreyle saklanmamalıdır. Ağ verisi sağlayıcısındaki geçici bir hatayı uzun süre önbelleğe almak, servis düzeldikten sonra da uygulamanın eski hata sonucunu göstermesine neden olur.
Eski verinin kullanılmasına izin veriliyorsa arayüz veya tüketen servis veri zamanını görebilmelidir. Arka planda yenileme, yalnız son bilinen değerin iş açısından kabul edilebilir olduğu durumlarda uygulanmalıdır. Ağ verisi sağlayıcısı değiştiğinde eski önbelleğin yeni sözleşmeyle uyumlu olduğu varsayılmamalı; kaynak ve şema sürümü üzerinden ayrım yapılmalıdır.
Uyarlayıcı Katmanıyla Ağ Verisi Sağlayıcısına Bağımlılığı Azaltma
Uygulamanın iş mantığı doğrudan sağlayıcının yanıtındaki veri alanlarının adlarına ve hata metinlerine bağlanırsa sağlayıcı değişimi geniş kod değişikliği gerektirir. Bunun yerine her sağlayıcı için dış yanıtı iç veri sözleşmesine dönüştüren bir adaptör kullanılmalıdır. İş mantığı yalnız bu kararlı iç modele erişmelidir.
Uyarlayıcı, kimlik doğrulama biçimini, uç noktayı, parametre adlarını, durum kodu yorumunu ve alan eşlemesini kapsar. Sağlayıcıya özgü özellikler iç modelde zorunlu hale getirilmemeli; sağlayıcının desteklemediği alanlar, desteklendiği halde değeri bilinmeyen alanlardan ayrılmalıdır.
Birden fazla sağlayıcı kullanılacaksa sonuçları sessizce birleştirmek yerine öncelik, geçiş koşulu ve kaynak görünürlüğü belirlenmelidir. Yaklaşık konum veya kuruluş adı farklı veri kümelerinde farklı çıkabilir. Yedek ağ verisi sağlayıcısından gelen sonuç, birincil sağlayıcının sonucuymuş gibi sunulmamalı; veri kaynağı ve sorgu zamanı korunmalıdır.
IP Adresi Sorgularında Gizlilik, Günlük ve Saklama Süresi
IP adresi tek başına her zaman belirli bir kişiyi göstermez; ancak hesap, zaman, cihaz veya oturum bilgileriyle birlikte kullanıldığında farklı etkinliklerin aynı kullanıcıyla ilişkilendirilmesini sağlayabilir. Bu nedenle sorgu hedefi, ham yanıt ve günlük alanları gereken en az veriyi toplama ilkesiyle seçilmelidir. Yasal sınıflandırma ülkeye ve işleme bağlamına göre değişebileceğinden, saklama kararı kurumun gizlilik ve uyum süreçleriyle doğrulanmalıdır.
Günlükler hata incelemesi için gerekli bağlamı taşımalı, fakat API anahtarını, tam yetkilendirme başlığını veya gereksiz ham yanıtı içermemelidir. Olay kimliği, ağ verisi sağlayıcısı, süre, sonuç sınıfı, önbellek durumu ve şema sürümü çoğu işletim incelemesi için yeterli olabilir. Ham IP adresine ihtiyaç yoksa adres hiç kaydedilmeyebilir veya kullanım amacına uygun biçimde maskelenebilir. Adresin kriptografik özetini almak tek başına anonimleştirme değildir; özellikle IPv4 adresleri olası değerler denenerek özetle eşleştirilebilir. Maskelenmiş veya özetlenmiş kayıtlar için de yeniden ilişkilendirme riski, erişim yetkisi ve saklama süresi değerlendirilmelidir.
Kayıt yönetimi yalnız veri toplamak değildir. Erişim yetkisi, bütünlük koruması, merkezi toplama, inceleme sorumluluğu ve silme süresi birlikte tanımlanmalıdır. Yaklaşık konum verisi GPS konumu veya açık adres olarak sunulmamalıdır. ASN ve operatör bilgisi de sorgulanan adresin ait olduğu ağı gösterir; bu ağın kullanıcısı olan kişiyi belirlemez. Sorgulanan adres bir VPN çıkışına, paylaşımlı internet çıkışına veya içeriği farklı sunuculardan dağıtan CDN hizmetine ait olabilir.
API Gecikmesi, Hata Oranı ve Sözleşme Testleri
Entegrasyonun sağlığı yalnız toplam başarı oranıyla ölçülmemelidir. Ağ verisi sağlayıcısı bazında gecikme, zaman aşımı, istek sınırı, şema hatası, önbellek isabeti, eski veri kullanımı ve yedek ağ verisi sağlayıcısının kullanımı ayrı ölçülmelidir. Ani alan kaybı veya veri türü değişimi, servis tamamen kesilmeden önce şema değişikliği uyarısı üretebilir.
Sözleşme testleri geçerli ve geçersiz IPv4/IPv6, uluslararası alan adı, izin verilmeyen DNS türü, boş alan, bozuk JSON, beklenmeyen içerik türü, büyük yanıt, zaman aşımı ve istek sınırı senaryolarını kapsamalıdır. Test verileri gerçek kullanıcı kayıtlarından alınmamalı; belgelendirme için ayrılmış adresler ve denetimli örnek yanıtlar kullanılmalıdır.
API Entegrasyonunu Kademeli Devreye Alma ve Geri Dönüş
Yeni entegrasyon önce düşük trafikle ve karar üretmeyen gözlem modunda çalıştırılabilir. Eski ve yeni sonuçlar kişisel veri saklama sınırları içinde karşılaştırılır; alan doluluk oranı, gecikme, hata dağılımı ve veri farklılıkları ölçülür. Kabul koşulları karşılanmadan bütün trafik yeni ağ verisi sağlayıcısına geçirilmemelidir.
- İç veri sözleşmesini ve uyarlayıcı sürümünü sabitleyin.
- Test, ön üretim ve üretim kimlik bilgilerini birbirinden ayırın.
- Düşük trafik yüzdesiyle gecikme, hata ve veri uyumunu ölçün.
- İstek sınırı, kesinti ve şema değişikliği senaryolarını kontrollü olarak deneyin.
- Önceki uyarlayıcıya dönüşü test edin; yalnız önbellekle devam edilecekse hangi verinin ne kadar eski olabileceğini ve uygun veri yokken verilecek hata sonucunu doğrulayın.
Geri alma yalnız kod sürümünü değiştirmek anlamına gelmez. Önbellek anahtarları, şema sürümleri, kuyruktaki işler ve sağlayıcıya özgü kayıtlar da geri dönüş planına dahil edilmelidir. Uygulama, dış servis kullanılamadığında yanlış veya uydurulmuş veri üretmek yerine açıkça sınırlı sonuç ya da kontrollü hata vermelidir.
