GÜNDEMDE

DÜNYADAN TEKNOLOJİ HABERLERİ

→
Yazılım

API tasarımında küçük kararların büyük etkileri

Zaman aşımı, tekrar deneme, durum kodları ve önbellek: gerçek projelerde fark yaratan ayrıntılar.

Yazılımcının GünlüğüYayımlanma: 15 Kas 20263 dk okuma

Sözleşme, endpoint'ten önce gelir

API kullanıcıya yalnızca veri değil davranış sözü verir. Hangi alanlar zorunlu? Hata durumunda ne döner? Tekrar edilen istek yeni kayıt oluşturur mu? Bu kararlar dökümante edilmeden uygulama büyüdükçe istemci davranışları çelişir.

Zaman aşımını tasarlayın

Bir API sonsuza kadar beklememelidir. Ancak çok kısa zaman aşımı, yavaş ama sağlıklı kaynakları hata gibi gösterebilir. Ölçülen gecikme yüzdeliklerine göre süre seçin; tekrar denemelerde üstel geri çekilme ve üst sınır uygulayın.

Doğru HTTP yanıtları

Geçici hizmet kesintisinde 503, bulunamayan kayıtta 404, çakışan eşzamanlı işlemde 409 kullanmak otomasyonların doğru karar vermesini kolaylaştırır. Her hataya 200 dönen sistemlerde izleme yanıltıcı hâle gelir.

Kavramsal iş akışı — editöryal çizim

Önbellekte güvenlik

Kişisel veri içeren bir yanıtı herkese açık önbelleğe yazmayın. ETag ve Cache-Control kullanırken yetkilendirme durumu ile varyasyonları hesaba katın. Ölçümü olmayan optimizasyon çoğu zaman görünmeyen hata üretir.

İstek sözleşmesi yalnız JSON alanlarından oluşmaz

Bir API tasarlarken hangi alanların zorunlu olduğunu, hangi durumda hata döndürüleceğini ve aynı isteğin tekrar gönderildiğinde ne yapacağını açıkça belirleyin. Örneğin ödeme oluşturma uç noktası tekrarlı isteği yeni ödeme sayarsa ağ kesintisi kullanıcıya iki kez ücret yansıtabilir. Hangi HTTP yönteminin veri değiştirdiği, istek gövdesinin boyut sınırı ve kimlik doğrulama kuralları belgeye dahil olmalıdır. Sunucu her sonucu 200 durum koduyla döndürürse kullanıcı ve izleme sistemleri başarıyla başarısızlığı ayırt edemez. API sözleşmesi yalnız yazılımcı için değil operasyon ekibi için de önemlidir.

Timeout ve retry sayısını ölçümden türetin

Çok kısa bir zaman aşımı sağlıklı ama yavaş yanıtları hata gibi gösterebilir; çok uzun bekleme ise sistemi kilitler. Gerçek istek gecikmesini ölçerek uygun sınır seçin ve tekrar denemeleri sınırlayın. 429 yanıtı hizmetin kota veya oran sınırını gösterir, Retry-After başlığı varsa dikkate alınmalıdır. 503 hizmet geçici kullanılamıyor anlamına gelebilir. Ancak geri alınamaz bir işlemi körlemesine tekrar denemek risklidir. İdempotent anahtar ve sonuç sorgulama olmadan yazma isteğinin tekrar edilmesi mükerrer kayıt üretmeye yol açabilir.

Önbellek, güvenlik ve canlı izleme

Herkese açık değişmeyen yanıtlar uygun süreyle önbelleğe alınabilir; oturuma bağlı yanıtlar paylaşılan önbelleğe konulmamalıdır. ETag gibi mekanizmalar gereksiz veri transferini azaltabilir fakat kullanıcı yetkisi değiştiğinde eski içeriğin görünmesi engellenmelidir. Üretimde istek kimliği, hata türü, yanıt süresi ve etkilenen kayıt sürümünü ilişkilendiren izleme düzeni kurun. 401, 403, 404, 409 ve 500 gibi kodları gerçek anlama uygun kullanın. Her düzeltmeden sonra mobil istemci, tarayıcı ve bağlı servislerin aynı sözleşmeyle çalıştığını doğrulayın.

0 okunma

Yorumlar

0 gerçek yorum

Henüz gerçek okuyucu yorumu yok.

✎ Yorum yaz

Yorumlar yayımlanmadan önce incelenir.