Sürekli Evrilen Ürünler için API Tasarımı

Ekranı değil, alanı modelleyin

Arayüzler arkalarındaki kavramlardan daha hızlı değişir. Belirli bir ekran etrafında kurulan bir API sunum durumunu açığa çıkarma ve yeni istemciler geldikçe yinelenen uç noktaları zorlama eğilimindedir. Kararlı alan kaynaklarıyla, yaşam döngüleriyle ve işin tanıdığı işlemlerle başlayın.

Bu teorik saflık gerektirmez. Ürün yüzlü bir API bir yolculuk için veri toplayabilir ama toplamanın net bir amacı ve sahipliği olmalıdır. Veritabanı tablolarını doğrudan sızdırmaktan kaçının; depolama yapısı sonunda değişmesi gereken bir uygulama ayrıntısıdır.

Uyumluluk bir özelliktir

Tüketiciler özellikle mobil uygulamalar ve dış entegrasyonlar farklı takvimlerde deploy eder. Ekleme değişiklikleri genellikle daha güvenlidir: yeni isteğe bağlı alanlar, yeni kaynaklar ve hoşgörülü okuyucularla yeni enum değerleri. Mevcut davranışı kaldırmak veya yeniden tanımlamak taşıma planı, telemetri ve yayımlanmış bir bitiş tarihi ister.

Sürümleme semantikler gerçekten ayrıldığında yararlıdır ama sürüm numaraları uyumluluk disiplinini değiştirmez. Sürümlü bir API yine de değişen sıralama, hata davranışı, limitler veya yetkilendirme yoluyla tüketicileri şaşırtabilir. Makine tarafından okunabilir bir şema tutun ve temsili tüketicileri ona karşı test edin.

• Bilinmeyen enum değerlerini güvenli ele alın
• Nullability ve varsayılanları belgelendirin
• Kritik tüketiciler için sözleşme testleri kullanın
• Kaldırmadan önce kullanımdan kaldırılmış alan kullanımını ölçün

Mutasyonlar kimlik ister

Güvenilmez ağlarda yeniden denemeler kaçınılmazdır. Önemli mutasyonlar için çağıran ve işleme kapsamlı bir idempotency anahtarı kabul edin. Sonucu saklayın ki tekrarlanan bir istek eylemi yeniden gerçekleştirmek yerine orijinal sonucu döndürsün.

Uzun süren iş açık durumlara sahip bir işlem kaynağı döndürmelidir. İstemciler kırılgan bir isteği açık tutmadan yoklayabilir veya abone olabilir. Bu desteği de iyileştirir: sistem işin kuyrukta, aktif, tamamlanmış veya başarısız olup olmadığını ve nedenini açıklayabilir.

Yetkilendirme sözleşmeye aittir

Kimlik doğrulama kimliği kurar; yetkilendirme o kimliğin bir kaynak üzerinde işlem yapıp yapamayacağına karar verir. Bunu sunucuda en dar anlamlı sınırda uygulayın. İstemcide bir düğmeyi gizlemek arayüz davranışıdır, erişim kontrolü değil.

Çok kiracılı sistemler istemci tarafından serbestçe sağlanıp güvenilmeyecek bir kiracı bağlamı ister. Kapsamı doğrulanmış üyelikten türetin, her kaynak erişiminde sahipliği doğrulayın ve idari eylemleri denetim ile soruşturma için yeterli bağlamla kaydedin.

Tüketici anlayışı için optimize edin

Tutarlı adlandırma, öngörülebilir sayfalama, yararlı hatalar, örnekler ve net bir değişiklik günlüğü entegrasyon süresini zekice protokol seçimlerinden daha fazla kısaltır. Bir API, tüketiciler iç tarihini öğrenmeden doğru kullanabildiğinde başarılıdır.

Tasarım incelemeleri istemci mühendislerini ve operasyonel senaryoları içermelidir. Arayüz ilk uygulamadan daha uzun yaşar; bu yüzden değiştirmesi en zor kısımlara hassasiyet harcayın: tanımlayıcılar, semantikler, yetkilendirme ve yaşam döngüsü.