API sözleşmesini tek doğruluk kaynağı hâline getirmek
API sözleşmesini tek doğruluk kaynağı hâline getirip istemcileri, tipleri ve doğrulamaları elle kopyalamak yerine otomatik türetmek, iyi tanımlanmış bir API içeren her projede uyguladığım bir yöntem.
Tipik ihtiyaç
Birden fazla tüketicinin — bir ön yüz, bir mobil uygulama, dış bir iş ortağı — kullandığı bir API'nin bulunduğu projelerde, veri alışverişi sözleşmesinin tarifi çoğu zaman birkaç yere kopyalanır: arka uç koduna, ön yüz koduna, ayrı bir dokümantasyona. Bu kopyalar zaman içinde neredeyse kaçınılmaz biçimde birbirinden ayrışır; arka uçta adı değiştirilen bir alan ön yüzde aynı anda güncellenmez, dokümantasyon kimsenin fark etmediği bir anda yanlış hâle gelir.
Bu tür ihtiyaçlarda nasıl çalışıyorum
OpenAPI spesifikasyonu; bir API'nin uç noktalarını, parametrelerini, istek ve yanıt biçimlerini araçlar tarafından okunabilen yapılandırılmış bir formatta ayrıntılı olarak tanımlar. Bunu iş bittikten sonra yalnızca dokümantasyon amacıyla yazmak yerine, projenin doğruluk kaynağı olarak ele alıyorum: arka uç kodu bu spesifikasyondan üretilebilir veya ona göre doğrulanabilir; daha da önemlisi istemci kodu (tipler, çağrı fonksiyonları, doğrulamalar) her tüketici için elle kopyalanmadan otomatik üretilir.
Bu yaklaşım bir hata sınıfını canlı ortamda çalışma anından derleme ya da kod üretme anına taşır: spesifikasyonda adı değişen bir alan, haftalar sonra bir kullanıcı tarafından keşfedilen bir hata yerine, istemci kodu üretimini anında ve yeri belli açık bir hatayla durdurur. İlk kurulum, her API değişikliğinde spesifikasyonun güncellenmesi disiplinini gerektirir; bu da teknik bir zorluktan çok bir alışkanlık değişimidir.
Fiyatlandırmayı etkileyen faktörler
-
Mevcut API mi, tasarlanacak API mi
Hâlihazırda çalışan bir API'yi belgelemek, API oluşturulurken spesifikasyonu baştan tasarlamaktan farklı bir yeniden kurgulama çalışması ister.
-
API'yi kullanan tüketici sayısı
Otomatik üretimin faydası, sözleşmeyle senkron tutulması gereken farklı istemci sayısı arttıkça büyür.
-
Veri tiplerinin karmaşıklığı
İç içe geçmiş ya da çok sayıda doğrulama durumu içeren veri yapıları, yazması ve bakımı daha zahmetli, çok daha ayrıntılı bir spesifikasyon gerektirir.
-
Geliştirme zincirine entegrasyon
Ara sıra elle üretim yapmak yerine her spesifikasyon değişikliğinde üretimi otomatikleştirmek, projenin araç setinde ek bir ilk kurulum çalışması gerektirir.
Sıkça sorulan sorular
Bu yaklaşım hâlihazırda canlıda olan bir API için de geçerli mi?
Bu yöntemi benimsemek için dil veya framework değiştirmek gerekir mi?
Spesifikasyon güncel tutulmazsa ne olur?
İhtiyacınızı bir dakikada anlatın
Size bir anket daha değil, doğrudan bir tahmin sunabilmem için birkaç hedefli soru.