FDE Foundations · Modül 4: Yazılım Zanaatı
Küçük API'ler Tasarlamak
Müşteriye dönük entegrasyon kodu yıllarca yaşar. Sıkı doğrulama, sayfalama ve sürümleme olan küçük, sıkıcı API'ler iyi yaşlanır; zekice olanlar yaşlanmaz.
11 dk okuma
Kazanımlar
- Sınırda doğrulamalı, kaynak odaklı uçlar tasarlamak
- Birinci günden sürüm ve sayfalama eklemek
- Yalnız mutlu yolu değil hata sözleşmesini belgelemek
Kaynak düşüncesi
Uçları müşterinin tanıdığı kaynaklara ve eylemlere göre adlandır: faturalar, çalıştırmalar, dışa aktarımlar. Yüzeyi küçük tut: API'de on uçtan fazlaysa entegrasyon iki taraf için de zorlaşıyor demektir. Çok sayıda dar işlem yerine girdileri net birkaç işlemi yeşle.
Sınırda doğrula
Her girdiyi kenarda ayrıştır ve doğrula: türler, uzunluklar, aralıklar, biçimler ve izin kontrolleri tek yerde. Müşterinin entegrasyonunun dallanabilmesi için makine okunur kodlarla yapılandırılmış hatalar döndür. Hata sözleşmesinin başarı sözleşmesi kadar titiz belgelenmesi, destek talebiyle günlük satırı arasındaki farktır.
Erken sürümle ve sayfala
v1 tek sürüm olsa bile ilk yayından itibaren sürüm öneki ya da başlığı ekle. Sürümlemeden alan yeniden adlandırmak müşteri kodunu kırar ve güveni yıpratır. Her liste ucunu sayfala; ikinci hafta birisi 100.000 satır isteyecek.
Gerçeği belgele
API referansını işleyici kodundan yaz ya da üret ve her uç için en az bir hata örneği ekle. Belgelenmemiş davranış, tersine mühendislikle çözülür olur ve tersine mühendislik yapılmış entegrasyonlar kibarca kırılmaz.
Mini kontrol
2-3 soruluk isteğe bağlı öz kontrol. Yanıtlar cihazından çıkmaz, saklanmaz ve hiçbir değerlendirmeye sayılmaz.
Alıştırma
Kurgusal bir fatura durumu servisi için API tasarlayın: dört uç, girdi doğrulama kuralları, üç hata kodu ve liste ucunda sayfalama. Bir hata yanıtını JSON olarak gösterin.
Geçme kriterleri
Metotları ve yollarıyla dört uç, alan başına doğrulama kuralları, anlamlarıyla hata kodları, bir sayfalama şeması ve bir JSON hata örneği bulunmalıdır.