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.
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.
Ö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.
Yorumlar
0 gerçek yorumHenüz gerçek okuyucu yorumu yok.
✎ Yorum yaz