عندما تفكك API دون إشعار، يمكنك تفكيك الثقة
TL;DR: يجب عليك إصدار API الخاص بك لتجنب إزعاج العملاء الحاليين عند إجراء التغييرات.
TL;DR: يجب عليك إصدار API الخاص بك لتجنب إزعاج العملاء الحاليين عند إجراء التغييرات.
مشكلات
- التطبيقات المستخدمة تحطم
- فشل التكامل
- انتهاك قواعد التفاؤل الأدنى
- Downtime
- الثقة القاتلة
- لعبة Rollbacks المطلوبة
- وقت التطوير ضائع
- تراجع تجربة المستخدم
حلول
- اشترى نسخة Semantic
- إدخال التوافق الخلفي
- إنشاء تحذير من الاكتئاب
- إنشاء خطوط الطريق
- الاستفادة من التفاوض على المحتوى
- إرسال إصدارات متوازنة
- تحديد التغيرات في وقت مبكر
- إزالة الخصائص تدريجياً
- بيانات تغير التغييرات بشكل واضح
- تحقق من النماذج المفقودة مع التسجيل
- اختبار إصدارات جديدة بشكل كامل
- إزالة الوظائف المفقودة بعد الزوال
السياق
عندما تقوم بتعديل API دون تحديد الإصدار الصحيح، يمكنك إنشاء التغييرات التي تؤثر على جميع العملاء الحاليين.
أنت تدفع المستهلكين إلى تحديث رمزهم على الفور أو تواجه مشكلات في النظام.
أنت تقف مع العقد المباشر بين الموردين API والمستهلكين.
وتعتمد البرمجيات الحديثة بشكل كبير على استقرار API ، ويمكن إدخال التغييرات المتكررة دون تحذير من أن تكون قادرة على خلق مشاكل في جميع أنحاء الأنظمة المعتمدة.
هذا مهم اليوم أكثر من أي وقت مضىالعديد من الشركات المصنعة للهواتف الذكية تطبق حلولها باستخدام توثيق API الحالي..
عندما تقوم بتحديث API دون الحفاظ على التوافق الخلفي ، فإنك تخاطر بتفريغ جميع التطبيقات التي تعتمد عليها.
هذا يخلق عدم الاستقرار والفرح والعديد من الإصلاحات تكلفة للمستخدمين.
غالبًا ما يتحمل العملاءالفسادفي وظائف جديدة، ولكن لا يزال سلوكًا مستقرًا.
توفير الإصدار الصحيح يضمن التغييرات السريعة ويحافظ على موثوقية نظامك.
رمز نموذج
خطأ 🙂
// 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;
});
حقًا 🙂
// 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;
});
اكتشاف
- [x] الذكور الذكور
يمكنك اكتشاف هذا الرائحة عند العثور على APIs التي تغير أسماء المجالات، أو إزالة المجالات، أو تغيير هيكلات البيانات دون الحفاظ على التوافق الخلفي.
ابحث عن التطبيقات المستخدمة التي تنتهي بعد تطبيقات API.
تحقق من أخطاء الإصدارات المفقودة أو خطط إصدارات URL.
مراقبة سجلات الأخطاء للارتفاعات المفاجئة في أخطاء المستخدم بعد الإصدارات.
اليوم ️
- APIs
مستوى
- [x] المتوسط
لماذا هو مهم ️
يجب عليك الحفاظ على مستقرخريطةبين عقد API الخاص بك ومتطلبات العملاء.
عندما تقطع هذاالتفاعلمن خلال تغيير API دون إصدارات، أنت تتناقض مع المبادئ الأساسية التي يمكن للمستخدمين الاعتماد عليها في وسائل الاتصال المتوافقة.
يمكنك إنشاء تناقض بين ما يتوقع العملاء الحصول عليه وما يقدم API الخاص بك.
هذا يفقد الترابط بين التزامات API و توزيع API ، مما يؤدي إلى فشل النظام وفقدان الثقة.
عندما تفكك الخرائط بين API الخاص بك واللوجستية التجارية التي تعكسها، فإن العملاء لا يمكنهم التفاعل مع النظام بشكل موثوق به.
هذا الاختلاف يؤدي إلى أخطاء، وقت إغلاق، نقص الثقة، وتجربة مستخدمة سيئة.
أجيال
غالبًا ما يخلق منتجات الذكاء الاصطناعي هذه الرغبة عندما تتطلب منهم "تعزيز" أو "تحديث" API موجودة.
إنها تركز على جعل API "أفضل" دون النظر في التوافق المفاجئ.
تحتاج إلى تدريب أدوات الذكاء الاصطناعي بشكل واضح على الحفاظ على أسماء المجالات الموجودة وإضافة إصدارات عند إجراء التغييرات.
غالباً ما يفضلون التصميم النظري على الاستقرار، إلا إذابالتفصيلأخبرني غيره
تقييم
يمكن للمنشآت الذكية إصلاح هذه الرطوبة عند توفير إرشادات واضحة حول استراتيجيات إصدار API.
ينبغي أن تتطلب منهم إدخال إصدارات معيّنة، والحفاظ على التوافق الخلفي، وبناء مسارات التهجير للميزات المفقودة.
احرص على ذلك!
تذكر: المساعدات الذكية تجعل الكثير من الأخطاء
الترجمة الموصى بها: إنشاء نسخة API لتجنب إزالة التغييرات
الترجمة الموصى بها: إنشاء نسخة API لتجنب إزالة التغييرات
Without Proper Instructions |
With Specific Instructions |
---|---|
النتيجة
يجب عليك دائمًا إصدار API الخاص بك من أجل منع التغيير من التأثير على التطبيقات المستخدمة.
حتى من النسخة الأولى.
عند الحفاظ على عقود ثابتة من خلال إصدارات مناسبة، يمكنك بناء الثقة مع مستخدمي API وتتيح تطورًا سليمًا من أنظمةك.
التغيرات المزمنة، ولكنها لا ينبغي أن تفقد عملاءك.
دائمًا نسخة API الخاصة بك، والتركيز بعناية، والاتصال بجدية لتجنب الإزعاج غير الضروري.
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
الرائحة الكريهة هي مننظرية.
الائتمان
صورة منجانيارلو RevolledoذاكUnplash
API هي إلى الأبد، لذلك تصميمها بعناية
API هي إلى الأبد، لذلك تصميمها بعناية
مارتن Fowler
هذه المقالة جزء من سلسلة CodeSmell.