30 saniyelik özet

API, yani uygulama programlama arayüzü, yazılımların belirlenmiş kurallarla birbirleriyle iletişim kurmasını sağlar. API specification, bu iletişimin isteklerini, yanıtlarını ve davranış kurallarını tarif eden şartnamedir. API contract ise sağlayıcı ile tüketici sistemin bu kurallar üzerinden kurduğu beklentileri ifade eder. Buradaki sözleşme, teknik ve davranışsal anlaşma anlamındadır. Alan adlarının yanında iş anlamı, yetki, hata, tekrar deneme ve değişiklik kuralları da önemlidir. İş analistinin katkısı, teknik olarak geçerli bir yanıtın iş açısından neyi garanti ettiğini açıklığa kavuşturmaktır.

Neden önemli?

Bir sipariş oluşturma isteği gönderildiğini düşünün. Sistem siparişi kaydeder, fakat bağlantı kesildiği için yanıt karşı tarafa ulaşmaz. İsteği gönderen sistem işlemin başarısız olduğunu varsayarak tekrar denerse aynı sipariş ikinci kez oluşabilir. Kullanıcı açısından sorun bağlantı hatası olarak başlamış, operasyon açısından yinelenen işleme dönüşmüştür.

Bunun çözümü yalnızca daha açıklayıcı bir hata mesajı değildir. Siparişin hangi anda oluşmuş sayılacağı, tekrar isteğinin nasıl tanınacağı ve sonuç belirsizken tüketicinin ne yapacağı birlikte tanımlanmalıdır. Tüketici, API’yi çağıran yazılımdır; sağlayıcı ise bu çağrıya karşılık veren hizmettir.

Yönetici açısından API sözleşmesi, ekipler arasındaki bağımlılığın yönetimidir. Bir alanı değiştirmek, başka bir şirketin sipariş akışını veya raporlamasını etkileyebilir. Bu nedenle değişiklik değerlendirmesi yalnızca sağlayıcının geliştirme eforuna dayanamaz. Tüketicilerin geçiş maliyeti, koordinasyon ihtiyacı ve eski davranışın ne kadar süre destekleneceği de karara dahildir.

Terim nedir?

Bir API şartnamesi, erişilecek işlemleri ve bu işlemlerin veri yapılarını tanımlar. HTTP üzerinden çalışan bir API’de uç nokta, belirli bir işlemin erişim adresidir. İstek şeması, gönderilecek alanların türlerini ve zorunluluklarını; yanıt şeması ise dönecek verinin yapısını belirtir. Şema, iş anlamının tamamını açıklamadığı için davranış tanımlarıyla desteklenmelidir.

Örneğin “durum” alanının metin olması yeterli değildir. Hangi değerleri alabileceği, değerlerin neyi temsil ettiği ve hangi geçişlere izin verildiği bilinmelidir. “Teslim edildi” ifadesi taşıyıcının beyanını mı, alıcının onayını mı gösteriyor? Bu ayrım, aynı veriden farklı iş sonuçları çıkarılmasını önler.

Kimlik doğrulama, çağrıyı yapanın kim olduğunu belirler. Yetkilendirme ise bu kimliğin hangi kaynağa hangi işlemi uygulayabileceğini sınırlar. Geçerli bir kimliğe sahip olmak, bütün siparişleri değiştirme hakkı anlamına gelmez. Sözleşme, bu sınırı tüketici ekiplerin anlayacağı biçimde açıklamalıdır.

İdempotency, aynı işlemin tanımlanmış koşullarda tekrarlanmasının ek bir iş etkisi oluşturmamasıdır. Örneğin aynı sipariş oluşturma talebi yinelendiğinde yeni sipariş açılmaması hedeflenebilir. Bunun için kullanılan anahtarın kapsamı, saklanma süresi ve farklı içerikle tekrar kullanımının sonucu belirlenmelidir. Anahtar göndermek tek başına bu davranışı garanti etmez.

Ayrıca çağrı sıklığı sınırları, geçici hatalarda yeniden deneme koşulları ve sürüm politikası açıklanır. Geriye uyumluluk, değişiklik sonrası mevcut tüketicilerin desteklenen davranışlarla çalışmaya devam edebilmesidir. Alanın adı ve türü korunurken anlamının değiştirilmesi de bu beklentiyi bozabilir.

Gerçek vaka: Stripe’ın alan değişikliği ve sürüm yaklaşımı

Stripe’ın 2017 tarihli teknik yazısı, banka hesabının doğrulanma durumunu gösteren verified alanını örnek olarak ele alıyor. Alan, doğru veya yanlış değeri alan bir yapıyken daha fazla durumu ifade edebilen status alanına dönüştürülmüş. Eski alanı bekleyen tüketici kodu, alan doğrudan kaldırıldığında çalışamaz hale gelebilir.

Şirket, yazının yayımlandığı dönemde hesapları belirli API sürümlerine bağladığını ve istekte sürüm seçimine izin verdiğini anlatıyor. Böylece yeni davranışın mevcut entegrasyonlara kontrolsüz biçimde ulaşması önleniyor. Değişiklikler ayrıca şirket içi API incelemesinden geçiriliyor.

Yazı, eski sürümleri desteklemenin bakım maliyetini de kabul ediyor. Dolayısıyla sürümleme, değişikliğin maliyetini ortadan kaldırmıyor; geçişi yönetilebilir hale getirmeyi amaçlıyor.

Bu vakadan çıkarılabilecek analiz dersi, bir alan değişikliğinin yalnızca veri modeli kararı olmadığıdır. Tüketici sistemin karar mantığı o alana bağlı olabilir. Değişiklik değerlendirmesinde hem yeni ihtiyacı hem de mevcut bağımlılıkları görmek gerekir. Burada aktarılan yaklaşım, tarihli teknik yazının anlatımıdır; Stripe’ın bugünkü bütün sürüm kurallarını temsil ettiği varsayılmamalıdır.

Kaynak: Brandur Leach, Stripe, APIs as infrastructure: future-proofing Stripe with versioning, 5 Ağustos 2017.

Varsayımsal örnek: Pazaryerinde sevkiyat oluşturmak

Bir pazaryeri, satıcıların siparişleri için sevkiyat kaydı oluşturabilecekleri bir API sunuyor. İş hedefi, taşıyıcıya aktarılacak talebin izlenebilir biçimde kaydedilmesidir. Başarılı kayıt yanıtı, paketin taşıyıcı tarafından teslim alındığı anlamına gelmez. Bu olay ayrı bir durum değişikliğidir.

İş analisti; sipariş kimliğini, paket bilgilerini ve teslimat adresinin hangi sürümünün kullanılacağını netleştirir. Sevkiyat oluşturulduktan sonra adres değişikliğine izin verilmeyecekse, sınır iş kuralı olarak açıklanır. Tüketici, gönderdiği adresle kayıttaki adresin ilişkisini anlayabilmelidir.

Bu varsayımsal tasarımda aynı satıcı için aynı işlem anahtarı ve aynı içerikle gelen tekrarlar yeni sevkiyat oluşturmaz; mevcut kayıtla ilişkilendirilir. Anahtar farklı içerikle kullanılırsa istek reddedilir. Saklama süresi ayrıca kararlaştırılır ve yayımlanır. Süre belirsiz bırakılırsa tüketici, tekrar denemesinin ne zaman güvenli olduğunu bilemez.

İstek kaydedildikten sonra yanıt kaybolursa tüketici aynı anahtarla tekrar deneyebilir veya tanımlanmış sorgulama yoluyla sonucu öğrenebilir. Geçersiz adres, yetki eksikliği ve geçici hizmet sorunu aynı hata olarak bildirilmez. Her hata için kaydın oluşup oluşmadığı ve tüketicinin beklenen sonraki adımı açıklanır.

Sevkiyat durumuna yeni değer eklenmesi de tüketici ekiplerle değerlendirilir. Bazı sistemler tanımadığı durumları işleyebilirken bazıları yalnızca önceden tanımlanmış değerleri kabul eder. Bu nedenle “Sadece yeni değer ekledik” açıklaması, değişikliğin etkisini değerlendirmek için yeterli değildir.

Yaygın üç hata

  1. Şemayı bütün sözleşme sanmak

Alan türleri doğru olsa bile iş sonucu belirsiz kalabilir. Başarılı yanıtın neyi garanti ettiğini, durumların anlamını ve işlem sınırını yazın. “Talep alındı”, “kayıt oluştu” ve “operasyon tamamlandı” ifadelerini birbirinin yerine kullanmayın.

  1. Her hatada yeniden denemeyi önermek

Yetki hatası ile geçici bağlantı sorunu aynı davranışı gerektirmez. Yanıt alınamaması, işlemin gerçekleşmediğini kanıtlamaz. Tekrar denemenin güvenli olduğu koşulları ve belirsiz sonuçları sorgulama yolunu tanımlayın. Tüketiciyi tahminle işlem yapmaya zorlamayın.

  1. Değişikliği yalnızca sağlayıcı açısından incelemek

Alan kaldırılması, zorunluluk değişikliği veya yeni durum değerleri tüketiciyi etkileyebilir. Desteklenen tüketici davranışlarını değerlendirin, geçiş yöntemini açıklayın ve eski sürümün destek koşullarını paylaşın. Teknik uygulama tamamlanınca koordinasyonun da tamamlandığını varsaymayın.

Mini uygulama / şablon

Bir API işlemi seçin. Önce iş sonucunu tek cümlede yazın; ardından aşağıdaki alanları sağlayıcı ve tüketici ekiplerle doldurun.

İşlemin adı ve amacı
—
Sağlayıcı ve tüketici sistemler
—
Başarılı yanıtın garanti ettiği iş sonucu
—
Uç nokta ve işlem yöntemi
—
İstek alanları, türleri ve zorunlulukları
—
Alanların iş anlamı ve veri sözlüğü bağlantısı
—
Yanıt alanları ve durumların anlamı
—
Kimlik doğrulama ve kaynak bazında yetki
—
Doğrulama ve iş kuralı hataları
—
Geçici hata ve belirsiz sonuç davranışı
—
Tekrar isteği, anahtar kapsamı ve saklama süresi
—
Çağrı sınırları ve yeniden deneme koşulları
—
Sürüm, değişiklik ve geçiş politikası
—
Örnek istekler, yanıtlar ve açık kararlar
—

Son incelemede aynı talebin yinelenmesini, yanıtın kaybolmasını ve yetkisiz kaynak erişimini ele alın. Sözleşme testi, sağlayıcı ile tüketicinin üzerinde anlaştığı beklentileri doğrulayan testtir. Bu testler bütün iş sürecinin doğruluğunu tek başına kanıtlamaz; operasyonun gerçekten tamamlandığı senaryolar ayrıca değerlendirilmelidir.

İlgili terimler

Functional Requirement, Non-Functional Requirement, Business Rule, Use Case, Data Mapping ve Data Dictionary, Acceptance Criteria, Requirements Traceability Matrix, Change Request ve Impact Analysis, User Acceptance Testing