Bir API, iki kod parçası arasındaki geçici bir bağlantı değil; farklı ekiplerin ve sistemlerin üzerine davranış inşa ettiği uzun ömürlü bir sözleşmedir. Endpoint isimleri ve JSON alanları bu sözleşmenin yalnızca görünür kısmıdır. Hata davranışı, tekrar deneme kuralları, yetkilendirme, sürüm geçişi ve operasyonel sınırlar da aynı tasarımın parçasıdır.
Sözleşme önce gelir
Sağlam bir API tasarımı, tüketicinin hangi işi yapmak istediğini netleştirerek başlar. Kaynak adları, HTTP metotları ve durum kodları bu iş amacına hizmet etmelidir. Aynı hata için farklı endpoint’lerin farklı biçimde yanıt vermesi, tüketiciyi her entegrasyonda yeni savunma kodu yazmaya zorlar.
Hata yanıtında makine tarafından okunabilir kararlı bir kod, kullanıcıya veya geliştiriciye yönelik açıklama ve isteği takip etmeyi sağlayan bir kimlik bulunması operasyonu kolaylaştırır. Dahili stack trace veya hassas altyapı ayrıntıları ise sözleşmenin parçası olmamalıdır.
Tekrar deneme ve idempotency
Ağ üzerinde bir isteğin sonucunu her zaman kesin olarak bilemeyiz. Tüketici timeout aldığında sunucu işlemi tamamlamış olabilir. Ödeme, sipariş veya iş akışı başlatma gibi yan etkili işlemlerde körlemesine retry yapmak tekrar kayıt üretebilir.
Idempotency anahtarı, aynı mantıksal isteğin yeniden gönderildiğini sunucunun tanımasına yardımcı olur. Fakat anahtarın kapsamı, saklama süresi, aynı anahtarla farklı gövde gönderilmesi ve eşzamanlı isteklerin davranışı açıkça tanımlanmalıdır. Retry politikası da yalnızca belirli geçici hatalarda, artan bekleme ve rastgele gecikmeyle uygulanmalıdır.
Güvenlik ve trafik sınırları
Kimlik doğrulama, isteği kimin gönderdiğini; yetkilendirme ise bu kimliğin belirli kaynağa erişip erişemeyeceğini belirler. Bu iki kontrolün birbirine karıştırılması, özellikle kaynak kimliği URL’den alınan endpoint’lerde veri sızıntısına yol açabilir.
Rate limiting yalnızca kötü niyetli trafiği engellemek için değil, paylaşılan kapasiteyi adil kullanmak için de gereklidir. Limit aşıldığında istemciye ne zaman tekrar deneyebileceğini anlatan Retry-After ve ilgili limit başlıkları sunulmalıdır.
Webhook ve harici servis entegrasyonları
Webhook alan bir sistem, göndereni imzayla doğrulamalı, replay penceresini sınırlamalı ve aynı olayın tekrar gelebileceğini varsaymalıdır. İmzalanan ham gövdenin framework tarafından değiştirilmeden korunması kritik bir ayrıntıdır. Olay hızlıca kabul edilip asenkron işlenebiliyorsa, harici servisin timeout ve retry davranışı da daha iyi yönetilir.
Üçüncü taraf API’lerde timeout, kota, sürüm değişikliği ve eksik veri normal durumlar olarak ele alınmalıdır. GeoIP Service ve Google Search API gibi bu merkezde yer alan örnekler, harici veriyi tek bir ürün sözleşmesine dönüştürmenin farklı yönlerini gösterir.
İlgili içerikler
Aşağıdaki teknik yazılar protokolleri ve API kullanımını; projeler ise girdi doğrulama, dokümantasyon, trafik sınırları ve birden fazla servis yanıtını tek sözleşmede birleştirme kararlarını gösteriyor.
