ما هي استراتيجيات إصدار الـ API الرئيسية، وكيف تُهمِل (deprecate) إصدارًا؟

Question

IT Interview Practice · Accepted Answer

يتيح لك الـ versioning تطوير API بـ **تغييرات كاسرة (breaking changes)** دون كسر العملاء الحاليين. هناك ثلاث استراتيجيات سائدة، إضافةً إلى عملية إهمال (deprecation).

## الاستراتيجيات الثلاث

**1. URI versioning** — الإصدار في المسار.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
الأبسط والأوضح؛ سهل التوجيه والـ caching والاختبار في متصفح. العيب: إنه تقنيًّا ينتهك "الـ URI يعرّف موردًا" (للمستخدم نفسه الآن رابطان). هذا بلا شكّ الخيار الأكثر شيوعًا (GitHub، وStripe تاريخيًّا).

**2. Custom header versioning** — الإصدار يسافر في رأس (header).
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
يبقي عناوين URL نظيفة لكنه غير مرئي في متصفح وأصعب في الـ caching.

**3. Media-type (content negotiation) versioning** — الإصدار في `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
الأكثر "RESTful" (رابط المورد مستقر؛ وتمثيله وحده هو المُصدَّر)، لكنه الأقلّ سهولة للمستهلكين.

## ما الذي يُعدّ كاسرًا

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
التغييرات الكاسرة وحدها تحتاج إصدارًا جديدًا؛ أمّا التغييرات غير الكاسرة فأضِفها إلى الإصدار الحالي.

## عملية الإهمال

1. **أعلِن** بتواريخ في التوثيق وسجل التغييرات (changelog).
2. **أشِر وقت التشغيل** بـ headers ليلاحظ العملاء برمجيًّا:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **راقِب** استخدام الإصدار القديم وتواصَل مع المتّصلين المتبقّين.
4. **أنهِ الخدمة (Sunset)** فقط بعد أن ينخفض الاستخدام قرب الصفر.

## لماذا يهم

يسأل المُقابِلون هذا ليروا إن كنت تستطيع تنمية API في الإنتاج دون كسر العملاء المعتمدين عليه — قلق تشغيلي حقيقي، لا نظري. أقوى الإجابات تُبرز تمييزين: أولًا، أن **معظم التغييرات غير كاسرة** ولا ينبغي أن تطلق ترقية إصدار أصلًا (التغييرات الإضافية تدخل الإصدار الحالي)، مع حصر الـ versioning في التغييرات الكاسرة فعلًا؛ وثانيًا، أن *الاستراتيجية* أقلّ أهمية من *العملية* — جدول إهمال واضح مع headers `Deprecation`/`Sunset` ومراقبة الاستخدام هو ما يحمي المستهلكين فعلًا. يفوز URI versioning عمليًّا لوضوحه ودعم الأدوات له، لكن معرفة المفاضلات (الـ header والـ media-type يبقيان عناوين URL مستقرة وأكثر RESTful، على حساب قابلية الاكتشاف) تُظهر أنك تفهم فضاء التصميم لا مجرّد تقليد `/v1/`.

الاستراتيجيات الثلاث

ما الذي يُعدّ كاسرًا

عملية الإهمال

لماذا يهم

أسئلة ذات صلة