Müşterilerinize API Açmak: Anahtar, Kota ve Dokümantasyon

Kendi API ucunuzu müşteriye açmak, bir entegrasyona bağlanmaktan farklı bir iştir: bu kez kuralları siz koyuyorsunuz ve verdiğiniz sözü geri almak zorlaşıyor. Dışarıya açılan bir uç yayımlandıktan sonra onu kullanan tarafların yazılımı o biçime göre yazılır; alan adını değiştirmek artık sizin değil, hepsinin işi olur.

Bu yazı, dışarıya API açarken verilmesi gereken kararları topluyor: kimlik doğrulama, kota, hata biçimi, sürüm sözü ve doküman. Entegrasyona bağlanan taraf olarak dikkat edilecekleri API, webhook ve kuyruk mimarisi yazısında ele almıştık.

Kimlik doğrulama: anahtar nasıl verilir?

En yaygın yol her müşteriye ayrı bir anahtar vermektir. Anahtarın tek müşteriye ait olması zorunlu, çünkü bir anahtarın iptali diğerlerini etkilememeli. Ayrıca her anahtarın bir kapsamı olmalı: yalnızca okuyabilen anahtar ile sipariş açabilen anahtar ayrı olur.

Anahtar üretirken üç alışkanlık işi sonradan kurtarıyor. Birincisi anahtarı veritabanında açık metin olarak değil özetiyle saklamak; ikincisi her anahtara bir ad vermek, böylece müşteri kendi tarafındaki hangi sistemin hangi anahtarı kullandığını bilir; üçüncüsü aynı müşteriye ikinci bir anahtar verilebilmesi, böylece anahtar değiştirilirken kesinti olmaz. Sır yönetiminin kendi tarafını entegrasyon anahtarları ve sır yönetimi yazısında anlattık.

Kota ve hız sınırı neye göre konur?

Sınırsız açılan bir uç, tek bir müşterinin hatalı döngüsü yüzünden bütün müşterileri yavaşlatır. Sınır koymanın amacı kısıtlamak değil, bir tarafın diğerlerini etkilemesini önlemek. Kurulumda üç tür sınır birlikte kullanılır:

Sınıra takılan isteğe dönen cevap, ne zaman tekrar denenebileceğini söylemelidir. Bunu söylemeyen bir sınır, karşı tarafın daha sık denemesine yol açar ve yükü artırır. İstek sınırına takılan tarafın ne yapması gerektiğini entegrasyonda 429 istek sınırı ve yeniden deneme yazısında anlattık; aynı davranışı kendi ucunuzda da beklemelisiniz.

Veri kapsamı: kim neyi görür?

Dışarıya açılan ucun en büyük riski yetki değil kapsamdır. Müşterinin anahtarıyla gelen istek yalnızca o müşterinin kayıtlarını görmeli; listelerde, aramada ve tek kayıt sorgusunda aynı kural geçmeli. Kayıt numarası elle değiştirildiğinde başka müşterinin kaydı açılabiliyorsa, kapsam yalnızca listede kurulmuş olur.

Bu konu dışarıya açılan uçlarda iç ekranlardan daha kritiktir, çünkü dışarıdan gelen istek bir ekranla sınırlı değildir. Kapsam kurallarının nasıl kurulduğunu kayıt bazlı yetki yazısında ayrıntılı ele aldık; dış uçlarda ek kural, anahtarın kendisinin bir kapsamı olması.

Veri çekme biçimi de kapsamın bir parçası. Karşı tarafın her sabah tüm kayıtları baştan çekmesi hem yükü artırır hem gereksizdir; değişenleri sorabileceği bir ölçüt sunmak gerekir. Bunun en basit hâli, kayıtların son değişiklik zamanına göre sorgulanabilmesi ve cevabın sayfalı dönmesidir. Sayfalama kurulurken sıralamanın sabit olması önemli: sıralama her istekte değişirse aynı kayıt iki sayfada görünür, bir kayıt hiç görünmez.

Hata biçimi ve sürüm sözü

Dışarıya açılan ucun hatası da bir sözleşmedir. Her hata cevabı aynı biçimde dönmeli: bir makine okuyabilir kod, bir insan okuyabilir açıklama ve mümkünse hangi alanın sorunlu olduğu. Aynı durum için bazen bir, bazen başka bir kod dönen uçta karşı taraf hata yönetimi yazamaz.

Sürüm tarafında verilecek söz nettir: yayımlanmış bir uçtan alan silinmez ve alanın anlamı değiştirilmez. Yeni alan eklemek güvenlidir, çünkü eski taraf onu okumaz. Kırıcı bir değişiklik gerektiğinde yeni sürüm açılır ve eskisi bir süre çalışmaya devam eder. Bu sürenin önceden duyurulması, karşı tarafın plan yapmasını sağlar. Sürüm geçişinin nasıl yönetildiğini API sürümü değişince entegrasyon bozulur mu yazısında anlatmıştık.

Doküman ve test ortamı

Doküman, API açmanın isteğe bağlı bir eki değil, parçasıdır. Dokümanı olmayan bir uç her müşteri için ayrı destek yazışması üretir ve o yazışmalar birbirinden farklı bilgiler içerir. Yeterli bir doküman şunları taşır:

• Her uç için örnek istek ve örnek cevap, gerçek alan adlarıyla.
• Hata kodlarının tam listesi ve her birinin anlamı.
• Kota ve sayfalama kuralları.
• Kimlik doğrulamanın nasıl yapıldığı ve anahtarın nasıl yenilendiği.
• Sürüm politikası ve geçmiş değişikliklerin kaydı.
• Test ortamının adresi ve test verisinin nasıl üretildiği.

Test ortamı ayrı bir maddedir: karşı tarafın canlı veride denemek zorunda kalmaması gerekir. Test ortamının canlı veriden ayrılmasını ve veri maskelemeyi test ortamı ve canlı veri maskeleme yazısında ele aldık.

Kısa kontrol listesi

• Her müşterinin ayrı anahtarı var; anahtarın kapsamı tanımlı.
• Anahtar özetiyle saklanıyor, adlandırılabiliyor, ikincisi verilebiliyor.
• Hız ve günlük kota var; sınıra takılan cevap ne zaman denenebileceğini söylüyor.
• Kapsam listede, aramada ve tek kayıt sorgusunda aynı çalışıyor.
• Hata cevapları tek biçimde ve kodlu.
• Yayımlanmış alan silinmiyor; kırıcı değişiklik yeni sürümle geliyor.
• Doküman ve test ortamı mevcut.

Özetle dışarıya API açmak teknik bir uç yayımlamak değil, bir söz vermektir: verdiğiniz biçim karşı tarafın yazılımına girer. KAV Yazılım dış uçları anahtar kapsamı, kota ve sürüm politikası birlikte tanımlanmış biçimde teslim ediyor.