Kural
Kaçınılması gerekenler kural kamu API sözleşmelerini
Değişiklikler değişiklikler genel API API değişiklikler olabilecek bozacak
mevcut istemci isteklerini şunlardır bozuluyor değişiklikler.
Düşünün şunu API'yi API sözleşmesini bir bir promise — değiştirme
değiştirmek değiştirmek değiştirmek bağımlı bağımlı buna bozulur kodlarını kodunu bozar.
Desteklenen diller: PHP, Java, C#, Python, JavaScript, TypeScriptGiriş
Halka açık API’ler, hizmetiniz ile bu hizmeti kullananlar arasındaki sözleşmelerdir. İstemciler bir uç noktanın istek biçimine, yanıt yapısına veya davranışına bağımlı hale geldiklerinde, bu unsurlarda yapılan değişiklikler istemcilerin kodlarında hataya neden olur. Geriye dönük değişiklikler, tüm istemcilerin aynı anda güncelleme yapmasını zorunlu kılar; ancak istemcileri kontrol edemediğiniz durumlarda bu genellikle imkânsızdır. Mobil uygulamalar zorla güncellenemez, üçüncü taraf entegrasyonlar için geçiş süresi gerekir ve eski sistemler hiçbir zaman güncellenmeyebilir.
Neden önemli?
Müşteri kesintileri ve güven: Ani API değişiklikleri, üretim ortamındaki istemci uygulamalarında anında arızalara yol açar. Kullanıcılar hatalarla karşılaşır, veri kaybı yaşar veya hizmetin tamamen kesilmesiyle karşı karşıya kalır. Bu durum, API sağlayıcıları ile tüketiciler arasındaki güveni zedeler ve istikrarlı API’lerin istikrarlı kalacağına dair zımni sözleşmeyi ihlal eder.
Koordinasyon maliyetleri: Birden fazla istemci ekibi arasında uyumsuzluklara yol açan değişiklikleri koordine etmek maliyetli ve zaman alıcıdır. Her ekibin kodu güncellemesi, değişiklikleri test etmesi ve devreye alması için zamana ihtiyacı vardır. İstemcileri bilinmeyen genel API’lerde (mobil uygulamalar, üçüncü taraf entegrasyonları) ise koordinasyon imkânsızdır.
Sürüm çoğalması: Kötü yönetilen geriye dönük uyumsuz değişiklikler, birden fazla API sürümünün aynı anda sürdürülmesine yol açar. Her sürüm için ayrı kod yolları, testler, belgeler ve hata düzeltmeleri gerekir; bu da bakım yükünü katlanarak artırır.
Kod örnekleri
❌ Uygun değil:
// Version 1: Original API
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({ id: user.id, name: user.name });
});
// Version 2: Breaking change - renamed field
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({
id: user.id,
fullName: user.name // Breaking: 'name' renamed to 'fullName'
});
});
Neden yanlış: name alanının adını fullName olarak değiştirmek, name alanını bekleyen tüm mevcut istemcilerin çalışmasını engeller. response.name alanına erişen istemci kodu, undefined değeriyle karşılaşacak ve bu da hatalara yol açacaktır. Bu değişiklik, tüm istemcilerin aynı anda güncellenmesini zorunlu kılar; aksi takdirde hata oluşur.
✅ Uygunluk:
// Version 2: Additive change - keeps old field, adds new
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({
id: user.id,
name: user.name, // Keep for backward compatibility
fullName: user.name // Add new field (deprecated 'name')
});
});
// Or use API versioning
app.get('/api/v2/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({ id: user.id, fullName: user.name });
});
Bunun önemi: Eskiyi korumak ad Bu alan, yeni özellikler eklerken geriye dönük uyumluluğu korur tamAdı yeni müşteriler için. Alternatif olarak, yeni bir sürüm numaralı uç nokta oluşturmak (/api/v2/) hâlâ bunu kullanan mevcut istemcileri etkilemeden uyumsuz değişiklikler yapılmasına olanak tanır /api/v1/.
Sonuç
API’leri kademeli değişikliklerle geliştirin: yeni alanlar ekleyin, yeni uç noktalar ekleyin, isteğe bağlı parametreler ekleyin. Geriye dönük uyumsuzluklar kaçınılmaz olduğunda, API sürümlemeyi kullanarak eski ve yeni sürümleri eşzamanlı olarak çalıştırın. Eski alanları kaldırmadan önce, net zaman çizelgeleri ve geçiş kılavuzları ile bu alanları kullanımdan kaldırılacağını bildirin.
