API Tasarımı: Sonradan Değiştirmesi En Zor Karar

Neden dikkatli tasarlanmalı?

API'yi kullanan taraflar ona bağımlı hale gelir. Bir alanın adını değiştirmek, tüm istemcileri bozabilir.

Bu yüzden API tasarımı, iç kod yazmaktan farklı bir disiplin gerektirir: geri uyumluluk baştan düşünülmelidir.

Adlandırma tutarlılığı

Kaynak adları çoğul ve tutarlı olmalıdır. Bir yerde tekil, başka yerde çoğul kullanmak sürekli hata üretir.

Alan adlandırma biçimini tüm API boyunca aynı tutun. Karışık biçimler istemci tarafında sürekli dönüştürme gerektirir.

Türkçe ve İngilizce karışımından kaçının. Hangisini seçerseniz seçin, tutarlı olun.

Hata yönetimi

Hatalar tutarlı bir yapıda dönmelidir: kod, anlaşılır mesaj ve gerekiyorsa alan bazlı ayrıntı.

Yanıt kodları doğru kullanılmalıdır. Her şeye başarılı kodu dönüp gövdede hata bildirmek, istemci tarafında kontrolü zorlaştırır.

Hata mesajları iç sistem ayrıntılarını sızdırmamalıdır. Veritabanı hata metinlerini doğrudan dönmek güvenlik açığıdır.

Sürümleme

API yayınlandıktan sonra kırıcı değişiklik yapmanız gerekebilir. Bunun için baştan sürümleme planı olmalıdır.

Adres içinde sürüm belirtmek en anlaşılır yöntemdir.

Eski sürümü ne kadar destekleyeceğinizi baştan ilan edin.

Geri uyumlu değişiklikler

Yeni alan eklemek genellikle güvenlidir. Alan kaldırmak veya anlamını değiştirmek kırıcıdır.

İstemcilerin bilmedikleri alanları yok saymasını beklemek makuldür ancak garanti edilemez; bu yüzden değişiklikleri duyurun.

Güvenlik

Her uç nokta kendi yetkisini kontrol etmelidir. Çağıranın yetkili olduğu varsayımı, dağıtık sistemlerde en yaygın açık kaynağıdır.

Kimlik doğrulama belirteçlerinin ömrü sınırlı olmalı ve yenileme mekanizması bulunmalıdır.

Hız sınırlaması koyun. Sınırsız erişim hem kötüye kullanıma hem de yanlışlıkla oluşan yük artışına açıktır.

Dokümantasyon

API dokümantasyonu kod ile birlikte güncellenmelidir. Elle yazılan ve ayrı tutulan doküman kaçınılmaz olarak eskir.

Her uç nokta için örnek istek ve yanıt bulunmalıdır. Kullanıcılar açıklamadan çok örneğe bakar.

Test edilebilirlik

API'yi kullanacak tarafın deneme yapabileceği bir ortam sunun.

Gerçek veri gerektirmeyen bir test ortamı, entegrasyon süresini belirgin biçimde kısaltır.

Sayfalama ve filtreleme

Liste dönen uç noktalarda sayfalama zorunludur. Sınırsız liste dönen bir uç nokta, veri büyüdüğünde sistemi düşürür.

Sayfalama biçimini baştan seçin ve tüm uç noktalarda tutarlı kullanın.

Filtreleme parametrelerini belgeleyin ve desteklenmeyen parametrelerde sessizce tüm veriyi dönmek yerine hata verin.

Sıralama seçeneklerini sınırlayın; her alanda sıralamaya izin vermek, indekslenmemiş sorgular üretir.

Kullanım ölçümü

Hangi uç noktanın ne sıklıkla ve kimler tarafından çağrıldığını ölçün.

Bu veri, hangi uç noktaların emekliye ayrılabileceğini gösterir. Kullanılmayan uç noktalar bakım yüküdür.

Yavaş yanıt veren uç noktaları izleyin; performans sorunları genellikle birkaç uç noktada toplanır.

Hata oranlarını istemci bazında görebilmek, entegrasyon sorunlarını karşı tarafa bildirmenizi sağlar.