API tasarımında sürümleme, hata yönetimi ve kimlik doğrulama

Bir API, onu kullanan tüm sistemlerle yapılmış bir sözleşmedir. Sözleşme tutarsız olduğunda her entegrasyon ayrı bir istisna kodu yazmak zorunda kalır; sözleşme değiştiğinde ise çalışan sistemler bir gecede bozulabilir. Bu yazıda REST tabanlı API tasarımında entegrasyonları dayanıklı kılan temel ilkeleri ele alıyoruz.

Kaynak odaklı ve tutarlı adlandırma

REST tarzı API'lerde adresler eylemleri değil kaynakları tanımlar. /orders bir sipariş koleksiyonunu, /orders/42 tek bir siparişi gösterir; işlemin türünü ise HTTP yöntemi (GET, POST, PUT/PATCH, DELETE) belirler. Çoğul isim kullanımı, tutarlı büyük-küçük harf biçimi ve öngörülebilir alan adları, API'yi öğrenmeyi kolaylaştırır.

• Aynı kavram için tüm uç noktalarda aynı alan adını kullanın.
• Tarih ve saatleri tek bir standart biçimde (ISO 8601) döndürün.
• Para birimi ve tutarı birlikte, belirsizlik bırakmayacak biçimde ifade edin.

Sürümleme: değişiklik kaçınılmazdır

Bir API zamanla değişir. Mevcut istemcileri bozmayacak değişiklikler (yeni isteğe bağlı alan eklemek gibi) aynı sürümde yapılabilir; mevcut davranışı değiştiren ya da alan silen değişiklikler ise yeni bir sürüm gerektirir. Sürüm bilgisi adreste (/v1/orders) ya da başlıkta taşınabilir; adreste taşımak genellikle daha görünür ve hata ayıklaması daha kolaydır.

Uygulamada dikkat edilecekler

• Eski sürümün ne zamana kadar destekleneceğini önceden duyurun.
• Kullanımdan kaldırılacak uç noktaları yanıt başlığı ve dokümantasyonla işaretleyin.
• İstemcilerin bilinmeyen alanları yok sayması gerektiğini sözleşmenin parçası yapın.

Tutarlı hata yanıtları

Hata yönetimi, API'nin en az özen gösterilen ama en çok fark yaratan kısmıdır. Doğru HTTP durum kodlarını kullanmak (doğrulama hatası için 422 ya da 400, yetki için 401 ve 403, bulunamayan kaynak için 404, hız sınırı için 429) istemcinin otomatik karar vermesini sağlar. Gövdede ise tüm uç noktalarda aynı yapı kullanılmalıdır.

• Makine tarafından okunabilir bir hata kodu ve insan tarafından okunabilir bir mesaj döndürün.
• Doğrulama hatalarında hangi alanın neden hatalı olduğunu alan bazında belirtin.
• Hata yanıtlarında yığın izi, sorgu metni ya da iç sistem bilgisi paylaşmayın.
• Her yanıta, destek talepleri için kullanılabilecek bir istek kimliği ekleyin.

Sayfalama, filtreleme ve sıralama

Koleksiyon döndüren her uç nokta sayfalamayı baştan desteklemelidir. Küçük veri kümeleri için sayfa numarası yeterli olabilir; sık değişen ve büyük veri kümelerinde imleç (cursor) tabanlı sayfalama daha tutarlı sonuç verir. Filtre ve sıralama parametreleri de adlandırma tutarlılığına tabidir ve izin verilen alanlar açıkça sınırlanmalıdır.

Kimlik doğrulama ve yetkilendirme

Kimlik doğrulama "kim olduğunuzu", yetkilendirme "ne yapabileceğinizi" belirler; ikisi ayrı ele alınmalıdır. Sunucudan sunucuya entegrasyonlarda kapsam (scope) sınırlı API anahtarları ya da OAuth 2.0 tabanlı akışlar; kullanıcı adına çalışan istemcilerde ise kısa ömürlü erişim belirteçleri ve yenileme belirteçleri yaygın yaklaşımlardır. Laravel gibi çerçevelerin sunduğu hazır mekanizmalar (örneğin Sanctum ya da Passport) bu ihtiyaçların çoğunu güvenle karşılar.

• Tüm trafiği yalnızca HTTPS üzerinden kabul edin.
• Anahtar ve belirteçleri en az yetki ilkesiyle verin ve döndürülebilir kılın.
• Her istekte yetkiyi sunucu tarafında yeniden denetleyin; istemcinin gönderdiği bilgiye güvenmeyin.
• Gizli anahtarları günlüklere ve hata yanıtlarına yazmayın.

Hız sınırı ve kötüye kullanımın önlenmesi

Hız sınırı hem sistemi korur hem de istemcilere beklenen kullanım düzeyini bildirir. Sınır aşıldığında 429 durum kodu ile birlikte ne zaman yeniden denenebileceğini belirten bir başlık döndürmek iyi bir pratiktir.

Idempotency: tekrar eden istekleri güvenli kılmak

Ağ hataları nedeniyle istemciler aynı isteği tekrar gönderebilir. Sipariş oluşturma veya ödeme gibi işlemlerde bu, çift kayıt anlamına gelebilir. İstemcinin gönderdiği benzersiz bir idempotency anahtarını saklayıp aynı anahtarla gelen isteği yeniden işlemek yerine ilk sonucu döndürmek bu riski ortadan kaldırır.

Webhook ve asenkron işlemler

Uzun süren işlemlerde isteği hemen kabul edip sonucu sonradan bildirmek daha sağlıklıdır. Webhook gönderirken imzalı istekler, yeniden deneme politikası ve tekrar eden bildirimlere karşı alıcı tarafında idempotent işleme önemlidir.

Dokümantasyon ve test

OpenAPI gibi makine okunabilir bir tanım, hem dokümantasyonu hem de istemci üretimini kolaylaştırır. Sözleşme testleri, API değiştiğinde entegrasyonların etkilenip etkilenmediğini erken gösterir.

Sonuç

İyi tasarlanmış bir API; tutarlı adlandırma, planlı sürümleme, öngörülebilir hata yanıtları, güvenli kimlik doğrulama ve tekrar eden isteklere dayanıklılık üzerine kuruludur. Sistemleriniz arasında entegrasyon kurmayı ya da mevcut bir API'yi gözden geçirmeyi planlıyorsanız, ihtiyacınızı bizimle paylaşabilirsiniz.