API tasarımı nasıl yapılır: tutarlı ve kullanılabilir arayüzler

İyi bir API'yi iyi yapan nedir?

API, bir yazılımın başka yazılımlarla konuşma sözleşmesidir. Kötü tasarlanmış bir API, yalnızca kullanan geliştiriciyi yavaşlatmaz; yayınlandıktan sonra değiştirmek zor olduğu için uzun süre teknik borç yaratır. Bu nedenle API tasarımı, kod yazmadan önce yapılan bir arayüz tasarımı işidir.

İyi API'nin ortak özellikleri vardır: tutarlı adlandırma, tahmin edilebilir davranış, açık hata mesajları, güvenli varsayılanlar ve iyi dokümantasyon. Bu özelliklerin amacı, API'yi ilk kez gören bir geliştiricinin kaynak koduna bakmadan doğru kullanımı tahmin edebilmesidir. Tasarım sırasında hep şu soru sorulur: bu API'yi kullanacak kişi neyi yanlış anlayabilir?

Kaynak odaklı tasarım ve HTTP yöntemleri

REST tarzı API'lerde temel fikir, sistemdeki varlıkları (sipariş, müşteri, ürün) kaynak olarak ele alıp adreslerle tanımlamak ve bunlar üzerindeki işlemleri HTTP yöntemleriyle ifade etmektir. Temel kurallar:

• Kaynak adları isim olur, fiil değil: siparişler için bir koleksiyon adresi, tek sipariş için o koleksiyonun altında bir kimlik.
• Okuma için GET, yeni kayıt için POST, kaydı bütünüyle değiştirmek için PUT, kısmi güncelleme için PATCH, silme için DELETE kullanılır.
• GET güvenli bir yöntemdir, sunucudaki durumu değiştirmemelidir. GET, PUT ve DELETE ayrıca idempotenttir: aynı isteği tekrarlamak sunucuda ilk istekten farklı bir etki yaratmaz. POST ise idempotent değildir, bu yüzden tekrar edilen ödeme ya da sipariş isteklerine karşı tekrar anahtarı gibi önlemler düşünülür.
• İlişkili kaynaklar hiyerarşik adreslerle gösterilir, ama iç içe seviye sayısı sınırlı tutulur.
• Liste uçlarında sayfalama, filtreleme ve sıralama baştan düşünülür.

Örneğin bir siparişi iptal etmek için "iptal-et" adlı bir fiil uç noktası eklemek yerine, siparişin durumunu güncelleyen bir işlem tanımlamak ya da iptali ayrı bir alt kaynak olarak modellemek daha tutarlıdır. Ancak her işlemi kaynak diliyle ifade etmek mümkün olmayabilir; bu durumda tutarlı bir istisna kuralı belirlenir.

Hata yönetimi ve yanıt tutarlılığı

Hata yanıtları API deneyiminin en çok ihmal edilen kısmıdır. Doğru durum kodunu kullanmak, istemcinin hatanın türünü anlamasını sağlar: istek hatası mı, yetki sorunu mu, kaynak bulunamadı mı, sunucu hatası mı. Yanıt gövdesinde ise makine tarafından okunabilir bir hata kodu, insan tarafından okunabilir bir açıklama ve mümkünse hangi alanın hatalı olduğu bulunmalıdır.

Tutarlılık önemlidir. Bir uç nokta hatayı bir biçimde, bir başkası başka biçimde döndürüyorsa istemci tarafında karmaşık kod gerekir. Tarih, para birimi ve kimlik alanları için de tek bir gösterim kuralı belirlenip her yerde uygulanmalıdır. Ayrıca hata mesajlarında hassas iç ayrıntıların ifşa edilmemesine dikkat edilir.

Versiyonlama ve geriye dönük uyumluluk

API yayınlandıktan sonra istemciler ona bağımlı hale gelir. Alan silmek, adını değiştirmek ya da davranışı değiştirmek istemcileri bozabilir. Bu yüzden değişiklikler uyumlu (yeni alan ekleme, yeni opsiyonel parametre) ve uyumsuz (alan silme, anlamı değiştirme) olarak ayrılır. Uyumlu değişiklikler mevcut sürümde yapılabilir. Uyumsuz değişiklikler ise yeni bir sürüm gerektirir.

Sürüm bilgisi adreste, başlıkta ya da medya türünde taşınabilir; seçilen yöntem tutarlı uygulanmalıdır. Eski sürüm için bir kullanımdan kaldırma planı yayınlanır: duyuru, geçiş süresi ve kapanış tarihi istemcilere önceden bildirilir. Sürüm sayısını düşük tutmak bakım yükünü azaltır, bu nedenle uyumsuz değişikliği ancak gerçekten gerekirse yapmak iyi bir ilkedir.

Güvenlik ve erişim kontrolü

API güvenliği tasarım aşamasında düşünülmelidir, sonradan eklenen bir özellik olarak değil. Temel başlıklar kimlik doğrulama (isteği yapan kim), yetkilendirme (bu işlemi yapmaya yetkisi var mı) ve girdi doğrulamadır. Yaygın yöntemler arasında anahtar tabanlı erişim ve belirteç tabanlı yetkilendirme çerçeveleri bulunur; hangisinin seçileceği kullanım senaryosuna bağlıdır ve ilgili standardın resmî dokümanından kontrol edilmelidir.

Bunun yanında hız sınırlandırma, kaynak düzeyinde yetki kontrolü (bir kullanıcı başkasının kaydına yalnızca kimlik değiştirerek erişememeli), şifreli iletişim ve günlük kaydı gibi önlemler gerekir. Dışarıya verilen veri en az gerekli kapsamda tutulur; yanıtta ihtiyaç olmayan alanlar gösterilmez.

OpenAPI ile dokümantasyon ve test

OpenAPI Specification, HTTP API'lerini dilden bağımsız, hem insanların hem makinelerin anlayabileceği biçimde tanımlamanın standart bir yoludur. Tanım dosyası uç noktaları, parametreleri, yanıtları ve veri şemalarını anlatır. Bu tanımdan etkileşimli dokümantasyon, istemci kodu ve sahte sunucu üretilebilir.

Önerilen yaklaşım, önce tasarlamak, yani kod yazmadan önce tanım dosyasını ekiple gözden geçirmektir. Böylece tasarım hataları kod yazıldıktan sonra değil, kağıt üzerindeyken yakalanır. Test tarafında Postman gibi araçlarla koleksiyonlar oluşturulur, otomatik doğrulama betikleri yazılır ve bunlar sürekli entegrasyon hattında çalıştırılır. Sözleşme testi, API'nin tanımına uygun davrandığını sürekli doğrular.

Sık yapılan hatalar ve öğrenme yolu

Yaygın tasarım hataları şunlardır:

• Uç noktaları veritabanı tablolarının birebir yansıması olarak tasarlamak
• Fiil içeren, tutarsız adlandırma kullanmak
• Her hatada aynı genel durum kodunu döndürmek
• Sürümlemeyi düşünmeden yayına çıkmak
• Sayfalama olmadan büyük listeler döndürmek
• Dokümantasyonu kod yazıldıktan sonraya bırakmak ve güncel tutmamak

Öğrenme yolunda önce HTTP protokolünü ve REST ilkelerini anlamak gerekir. Ardından kaynak modelleme, hata yönetimi ve sürümleme çalışılır. Sonraki aşamada güvenlik, geçit (gateway) yönetimi, izleme ve OpenAPI dokümantasyonu gelir. İleri aşamada API'yi bir ürün olarak yönetmek: kullanıcıları, kullanım ölçümü, yönetişim ve ekonomik değeri öne çıkar. Etkili bir pratik, mevcut tanınmış bir API'nin tasarımını inceleyip eleştirmek ve küçük bir API'yi sıfırdan tasarlayıp başkasına kullandırmaktır.

Mindset programlarında API tasarımı

Mindset kataloğundaki API Tasarımı ve Yönetimi programı; API tasarım prensipleri, versiyonlama ve evrim, API güvenlik, API gateway ve portal yönetimi, OpenAPI ve API dokümantasyonu, API izleme ve yönetişim ile API stratejisi ve ekonomisi başlıklarını içerir. Postman ile API Testi programı ise HTTP protokolü, koleksiyon ve ortam yönetimi, test betimleri, kimlik doğrulama ve güvenlik testi, mock server ve Newman ile CI/CD entegrasyonu modüllerine sahiptir.