Uyarı olmadan API'leri kırdığınızda, güveninizi kırıyorsunuz
TL;DR: Değişiklikler yaptığınızda mevcut müşterilerin kırılmasını önlemek için API'lerinizi sürümlendirmelisiniz.
TL;DR: Değişiklikler yaptığınızda mevcut müşterilerin kırılmasını önlemek için API'lerinizi sürümlendirmelisiniz.
Sorunlar
- Müşteri uygulamaları çöktü
- Integrasyon başarısızlığı
- En az sürpriz ilkesinin ihlali
- Downtime Hakkında
- Kırık Güven
- İhtiyaç Duyulan Rollbacks
- Geliştirme zaman kaybı
- Kullanıcı Deneyimi Degradasyonu
Çözümler
- Semantik versiyon ekleme
- Geri Dönüşüm Kompatibilitesi
- Döviz uyarıları oluşturun
- yol haritası oluşturmak
- İçerik müzakereleri kullanın
- Paralel versiyonları
- Değişiklikleri erken bildirin
- Anahtar Kelimeler Yavaş Yavaş
- Belge değişiklikleri açıkça kırmak
- Logging ile deprecated parametreleri kontrol edin
- Yeni versiyonları test edin
- Güneş batımından sonra bozulmuş işlevlerin kaldırılması
bağlamı
Uygun sürümleme olmadan API'leri değiştirirseniz, tüm mevcut istemcileri etkileyen yıkıcı değişiklikler oluşturursunuz.
Kullanıcıları kodlarını hemen güncelleştirmeye zorlarsınız veya sistem hataları ile karşılaşırsınız.
API sağlayıcıları ve tüketiciler arasındaki anlaşmayı ihlal ediyorsunuz.
Modern yazılım büyük ölçüde API istikrarına dayanır ve uyarı olmadan kırılgan değişiklikler uygulanması bağımlı sistemlerde kaskadalı hatalar yaratabilir.
Bugün her zamankinden daha önemliBirçok IA mevcut API belgelerini kullanarak çözümlerini oluşturur.
Bir API'yi geriye dönük uyumluluk tutmadan güncelleştirirseniz, buna bağlı olan tüm uygulamaları kırma riski yaşıyorsunuz.
Bu, kullanıcılar için istikrarsızlık, hayal kırıklığı ve pahalı düzeltmeler yaratır.
Müşteriler genellikleeksiklikleriyeni işlevlerde, ancak daha önce istikrarlı bir davranış kırılmadı.
Doğru versiyonlama, düzgün geçişleri sağlar ve sisteminizin güvenilirliğini korur.
Kod örnekleri
Yanlış
// user-api-v1.json - Original API response
{
"id": 317,
"name": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"nationalities": "Brazilian,Canadian,Oceanic"
}
// Later changed to this without versioning:
{
"userId": 317,
"fullName": "Mr Nimbus",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalities": ["Brazilian", "Canadian", "Oceanic"]
}
fetch('/api/users/317')
.then(response => response.json())
.then(user => {
// This breaks when API changes field names and data types
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
// This breaks when nationalities changes from string to array
document.getElementById('nationalities').textContent
= user.nationalities;
});
Doğru
// user-api-v1.json - Version 1 (maintained)
{
"id": 317,
"name": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"nationalities": "Brazilian,Canadian,Oceanic"
}
// user-api-v2.json - Version 2
// (new structure, backward compatible)
{
"id": 317,
"userId": 317,
"name": "Mr Nimbus",
"fullName": "Mr Nimbus",
"email": "nimbus@atlantis.com",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalities": "Brazilian,Canadian,Oceanic"
"nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}
// user-api-v3.json - Version 3
// (new structure, backward not compatible)
{
"userId": 317,
"fullName": "Mr Nimbus",
"emailAddress": "nimbus@atlantis.com",
"createdAt": "2018-12-09T18:30:00Z",
"nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}
// client-code-versioned.js
const API_VERSION = 'v1';
fetch(`/api/${API_VERSION}/users/317`)
.then(response => response.json())
.then(user => {
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
// V1 handles comma-separated string
document.getElementById('nationalities').textContent
= user.nationalities;
});
// Or with content negotiation
fetch('/api/users/317', {
headers: {
'Accept': 'application/vnd.api+json;version=1'
}
})
.then(response => response.json())
.then(user => {
document.getElementById('name').textContent = user.name;
document.getElementById('email').textContent = user.email;
document.getElementById('nationalities').textContent
= user.nationalities;
});
Keşifler
- [x] Yarı otomatik
Bu koku, alan adlarını değiştiren, alanları kaldıran veya geri uyumluluğu sürdürmeden veri yapılarını değiştiren API'leri bulduğunuzda tespit edebilirsiniz.
API dağıtımlarından sonra kırılan müşteri uygulamalarını arayın.
Eksik versiyon başlıkları veya URL versiyon düzenlemeleri için kontrol edin.
Özelleştirmelerden sonra müşteri başarısızlıklarında aniden artışlar için hata günlükleri izleyin.
Güncel ️
- Apiş
Seviye
- [x] Ortaçağ
Why the Bijection Is Important 🗺️
istikrarlı bir şekilde devam etmelisinizHaritasıAPI sözleşmesi ve müşteri beklentileri arasında.
Bunu kırdığınızdabişeylerAPI'yi versiyonlandırmadan değiştirerek, müşterilerin tutarlı arayüzlere güvenebileceği temel ilkeyi ihlal ediyorsunuz.
Müşterilerinizin almayı beklediği ve API'nizin sağladığı şey arasında bir çelişki yaratırsınız.
Bu, API vaatleri ve API teslimatı arasındaki tek-bir uyumunu kırar, sistem başarısızlıklarına ve güven kaybına neden olur.
API'lerin gerçek dünya hizmetleri modeli. API'nizin ve temsil ettiği iş mantığı arasındaki haritayı kırdığınızda, müşteriler sisteminizle güvenilir bir şekilde etkileşime giremez.
Bu çelişki kusurlara, durdurma zamanlarına, güven eksikliğine ve kötü bir kullanıcı deneyimine yol açar.
Bu nesil
AI jeneratörleri genellikle mevcut API'leri "geliştirmek" veya "güncellemek" için onlara sorduğunuzda bu kokuyu yaratır.
Geri uyumluluğu göz önünde bulundurmadan API'yi "daha iyi" yapmaya odaklanıyorlar.
Mevcut alan adlarını korumak ve değişiklikler yaparken sürümleme eklemek için açıkça AI araçlarını yönlendirmelisiniz.
Çoğu zaman temiz tasarımı istikrarın ötesinde tercih ederler.explicitlyBaşka türlü söyledim.
Keşfedilecek Yerler
AI jeneratörleri, API sürümleme stratejileri hakkında net talimatlar verdiğinizde bu kokuyu düzeltebilir.
Onlara semantik versiyonlama uygulamasını, geriye dönük uyumluluğu korumayı ve bozulmuş özellikler için geçiş yollarını oluşturmalarını isteyin.
Bunu deneyin!
Unutmayın: AI Asistanları Birçok Hata Yapar
Önerilen Prompt: Değişikliklerin kırılmasını önlemek için API sürümünü oluşturun
Önerilen Prompt: Değişikliklerin kırılmasını önlemek için API sürümünü oluşturun
|
Without Proper Instructions |
With Specific Instructions |
|---|---|
Sonuçlar
Her zaman API'lerinizi sürümlendirmelisiniz, böylece değişiklikler, müşteri uygulamalarını etkiler.
İlk versiyonundan bile.
Doğru sürümleme aracılığıyla istikrarlı sözleşmeleri sürdürdüğünüzde, API tüketicileriyle güven oluşturursunuz ve sistemlerinizin düzgün bir şekilde gelişmesini sağlarsınız.
Kırık değişiklikler kaçınılmazdır, ancak müşterilerinizi kırmamalıdır.
API'lerinizi her zaman sürümlendirin, dikkatlice temizleyin ve gereksiz kesintilerden kaçınmak için proaktif olarak iletişim kurun.
İlişkiler
https://hackernoon.com/misusing-http-status-codes-wrecks-your-api-monitoring-and-client-logic
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-iv-7sc3w8n
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxv
Disclaimer
Kokularım benimgörüşü.
Kredi
FotoğrafçılıkGiancarlo Revolledo HakkındaBenimUnsplash Hakkında
Api sonsuza dek var, bu yüzden dikkatli bir şekilde tasarlayın
Api sonsuza dek var, bu yüzden dikkatli bir şekilde tasarlayın
Martin Fowler hakkında
Bu makale CodeSmell serisinin bir parçasıdır.
