ما هو إصدار API
إدارة إصدارات API
إصدار API
إصدار API هو ممارسة إدارة تغييرات API مع الحفاظ على التوافق العكسي للعملاء الحاليين.
استراتيجيات الإصدار
| الاستراتيجية | مثال | الوصف | |--------------|------|-------| | مسار URL | /api/v1/users | الإصدار في مسار URL | | معلمة الاستعلام | /api/users?version=1 | الإصدار في المعلمة | | الرأس | X-API-Version: 1 | الإصدار في الرأس | | نوع المحتوى | Accept: application/vnd.api.v1+json | إصدار نوع الوسائط |
الإصدار الدلالي
- رئيسي (v1→v2) — تغييرات كاسرة
- ثانوي (v1.1→v1.2) — ميزات جديدة، متوافق عكسياً
- تصحيح (v1.1.0→v1.1.1) — إصلاحات الأخطاء
أفضل الممارسات
- توثيق جميع التغييرات (سجل التغييرات)
- دعم إصدارين على الأقل
- الإعلان عن الإهمال مسبقاً
- استخدام رؤوس sunset
- توفير أدوات الترحيل
متى يلزم إصدار جديد
- إزالة الحقول أو نقاط النهاية
- تغيير تنسيق الاستجابة
- تغيير دلالات المعلمات
- تغيير المصادقة