Soyutlama Yok: API Tasarımı İlkelerimiz

• API kaynaklarını adlandırma ve modelleme kararları, API tasarımının en zor ve en önemli kısmıdır. Kaynaklar, kullanıcının ürünün nasıl çalıştığına ve hangi işlevlere sahip olduğuna dair zihinsel modelini oluşturur.
• Increase ekibi, API tasarımını yönlendirmek için "soyutlama yok" ilkesini kullanıyor.

Stripe'ın API tasarım yaklaşımı

• Ekibin önemli bir kısmı daha önce Stripe'ta çalışmıştı ve Stripe'ın başarılı API tasarım değerlerini dikkate alıyor.
• Stripe, karmaşık bir alanın temel işlevlerini kullanıcıların kolayca anlayıp kullanabileceği soyutlamalara dönüştürmede çok başarılıdır. (Örn. Visa ile Mastercard arasındaki farkı soyutlayan PaymentIntent)
• Stripe kullanıcılarının çoğu, ödeme ile ilgisi olmayan ürünler geliştiren erken aşama girişimlerdir; kredi kartlarının ayrıntılarını bilmeleri gerekmez. Bu kullanıcılar Stripe'ı hızlıca entegre edip ürün geliştirmeye odaklanmak ister.

Increase kullanıcıları ve API tasarım ilkesi

• Buna karşılık, Increase kullanıcıları ödeme ağları hakkında derin bilgiye sahiptir ve Increase'ı seçme nedenleri de doğrudan ağ bağlantısı ve entegrasyon derinliğidir.
• Bu kullanıcılar, FedACH penceresinin tam olarak ne zaman kapandığını ve havalenin ne zaman gerçekleştiğini bilmek ister; ayrıca ACH transferlerinde farklı SEC kodu ayarlarının iade zamanlamasını etkileyebileceğini de anlar.
• Bu ağların temel karmaşıklığını gizlemeye yönelik girişimler, hayatı basitleştirmek yerine yalnızca kullanıcıları rahatsız eder.
• İlk kullanıcılarla yapılan görüşmeler sonucunda "soyutlama yok" ilkesi çıkarıldı ve API tasarımına uygulandı.

"Soyutlama yok" ilkesinin API tasarımına etkisi

• Gerçekte kullanılan terimleri kullanma: API kaynakları ve özellikleri için yeni adlar uydurmak yerine, alttaki ağın söz varlığı kullanılır. (Örn. ACH transfer parametreleri için Nacha spesifikasyonundaki alan adları kullanılır)
• Değişmezlik: Gerçek olaylar model alınarak daha fazla API kaynağının değişmez olması sağlanır. Değişmez kaynak kümelerini durum makinesi biçimindeki "yaşam döngüsü nesneleri" olarak gruplamak etkili olur. (Örn. ach_transfer nesnesinin status alanı ve transfer yaşam döngüsüne göre oluşturulan birkaç değişmez alt nesne)
• Kullanım senaryosuna göre kaynakların ayrılması: Bir kaynak örneğine bağlı olarak kullanıcının yapabileceği işlemler kümesi büyük ölçüde farklıysa, bunlar birden fazla kaynağa bölünür. (Örn. giden ACH transferi ile gelen ACH transferi ayrı kaynaklara ayrılır)

Mühendislik ekibinin bu yaklaşıma bağlı kalması

• Mühendislik ekibi bu yaklaşıma bağlı kalmayı taahhüt etti.
• Karmaşık bir API'yi yıllar boyunca tasarlarken sürekli küçük artımlı kararlar vermek gerekir; önceden temel ilkelere bağlı kalma taahhüdü, bu kararların getirdiği bilişsel yükü azaltır.
• Örneğin Federal Reserve'e para gönderirken gereken Input Message Accountability Data alanı için, yüksek soyutlamalı bir API'de bu alana nasıl daha "kullanıcı dostu" bir ad verileceği düşünülürdü. Increase'te ise mühendis alan adını input_message_accountability_data olarak belirleyip yoluna devam eder.

GN⁺ görüşü

• API'nin soyutlama seviyesi, ilgili ürün alanında geliştiricinin deneyim düzeyine ve entegrasyona ne kadar enerji ayıracağına göre değişebilir. Bu nedenle API tasarlarken, entegre edecek geliştiriciler için uygun soyutlama seviyesini düşünmek önemlidir.
• Yüksek soyutlamalı bir API kuruyorsanız, yeni özellik eklemeden önce dikkatlice düşünmelisiniz. Buna karşılık düşük soyutlamalı bir API kuruyorsanız, bu çizgiyi korumalı ve soyutlama ekleme cazibesine direnmelisiniz.
• Alttaki ağın veya protokolün terimlerini aynen kullanmak, geliştiricilerin underlying system'i anlamasına yardımcı olabilir; ancak öte yandan ilk kez karşılaşan geliştiriciler için giriş engeli de oluşturabilir. Bu yüzden iyi açıklamalar ve dokümantasyon sağlamak önemli görünüyor.
• API tasarımında immutable nesnelerden yararlanmak, veri tutarlılığını korumada ve side-effect'leri önlemede etkili olabilir. Ancak veri güncellemesi gerektiğinde tersine kullanışsızlık yaratabilir; bu nedenle trade-off'lar dikkatle değerlendirilmelidir.
• Kullanım senaryosuna göre kaynakları ayırmak API'nin karmaşıklığını artırabilir, ancak uzun vadede öngörülebilirliği yükseltebilir. Yine de aşırı parçalanırsa kullanılabilirlik düşebilir; bu yüzden uygun dengeyi bulmak önemlidir.

[GN⁺]

Hacker News görüşleri

• Hem düşük seviyeli soyutlamaya sahip API’ler hem de yüksek seviyeli soyutlamaya sahip API’ler sunmak iyi bir yaklaşım

  • Düşük seviyeli API’ler ayrıntılı kontrol sağlar, ancak uzmanlık bilgisi gerektirir
  • Yüksek seviyeli API’ler yaygın kullanım senaryolarına uygun, basitleştirilmiş işlemler sunar
  • İki API arasında net bir ayrım korunursa, her bir API’ye soyutlamalar veya özel durumlar ekleme baskısı azalır
  • İstemcilerin bir API’den diğerine nasıl geçeceğini öğrenebilmesi için dokümantasyon sağlamak faydalıdır

• Increase’in farklı bir yaklaşım seçme nedenini açıkladığı kısmı beğendim

  • Temel bir şeyi tasarlarken bağlam çok önemlidir, ancak insanlar genelde bunun yeterince farkında olmaz

• Stripe’ın gerçek gücü, müşterilerini tanıması ve onların istediği sadeliği sunmasıdır

  • Increase de müşterilerinin neye ihtiyaç duyduğunu iyi anlıyor ve harika bir ürün oluşturmak için tasarım ilkeleri geliştirmede benzer bir odak sergiliyor

• Domain-Driven Design’daki, uygulamada alan uzmanlarının kullandığı gerçek terimlerle aynı terimlerin kullanılmasını öneren "Ubiquitous Language" tasarım kalıbına benziyor

• Alan uzmanlarının anlayabileceği bir dil kullanılmalı

  • Eğer kullanıcı NACHA dosyalarının ne olduğunu biliyorsa, farklı terimler kullanmak onun zihninde sürekli eşleştirme yapmasını gerektirir
  • Stripe örneğinde kullanıcı alan uzmanı olmadığından, anlaşılır olup gereksiz ayrıntıları gizleyen soyutlamalar oluşturmak değerlidir

• POSIX gibi bir soyutlama olmasaydı, uygulamaların desteklenen her dosya sistemi için ayrı bir adaptör yazması gerekirdi

• API yapısının bazı bölümlerinin dışarıdan kontrol edilen bir spesifikasyona dayanarak bire bir kurulduğu söyleniyor

  • Bu tür spesifikasyonlar gelişir veya değişirse ne olur? Yeni bir API mi gerekir?

• Ödeme API’lerinde temiz biçimde modellemesi zor olan konulardan biri, ödeme ağlarının ödeme iadesi sırasında ödeyen ve alıcının rollerini farklı şekillerde temsil etmesidir

  • Örneğin bazı ağlarda ödeyen ve alıcı, ilk ödemedeki konumlarıyla aynı yerde kalabilir
  • Buna karşılık diğer ağlarda bu roller yer değiştirir