ما هي أفضل استراتيجية لإصدار واجهات برمجة التطبيقات: عنوان URL أم الرأس أم التفاوض على المحتوى؟

ملخص

ترقيم الإصدارات في عنوان URL (/v1/pets) هو استراتيجية ترقيم إصدارات واجهة برمجة التطبيقات (API) الأكثر عملية لمعظم الفرق. إنه مرئي، قابل للتخزين المؤقت، وسهل الاختبار. ترقيم الإصدارات في الرأس (Header versioning) وتفاوض المحتوى (content negotiation) أكثر "نقاءً" من منظور REST ولكنهما يضيفان تعقيدًا. تستخدم PetstoreAPI الحديثة ترقيم الإصدارات في عنوان URL مع الترقيم الدلالي للإصدارات وسياسات واضحة للإيقاف التدريجي.

مقدمة

تحتاج واجهة برمجة التطبيقات (API) الخاصة بك إلى تغيير مؤثر (breaking change). أنت بصدد تغيير تنسيق الاستجابة لـ /pets من مصفوفة مجردة إلى كائن مغلف ببيانات تعريف التصفح (pagination metadata). ستتعطل العملاء الحاليون. ماذا تفعل؟

أنت بحاجة إلى ترقيم إصدارات API. ولكن ما هي الاستراتيجية؟ ترقيم الإصدارات في عنوان URL (/v1/pets مقابل /v2/pets)؟ ترقيم الإصدارات في الرأس (Accept: application/vnd.petstore.v1+json)؟ تفاوض المحتوى؟ كل نهج له مؤيدون متحمسون وآراء قوية.

الإجابة: ترقيم الإصدارات في عنوان URL هو الأفضل لمعظم الفرق. إنه عملي، مرئي، ويعمل مع جميع أدوات HTTP. ترقيم الإصدارات في الرأس وتفاوض المحتوى أنظف نظريًا ولكنهما يضيفان تعقيدًا لا تحتاجه معظم الفرق.

تستخدم Modern PetstoreAPI ترقيم الإصدارات في عنوان URL مع الترقيم الدلالي للإصدارات وسياسات واضحة للإيقاف التدريجي. الإصدار الحالي هو v1، مع التخطيط لـ v2 للتغييرات المؤثرة المستقبلية.

💡

إذا كنت تقوم ببناء أو اختبار واجهات برمجة تطبيقات REST، فإن Apidog يساعدك على اختبار إصدارات متعددة من واجهة برمجة التطبيقات، والتحقق من السلوك الخاص بالإصدار، وضمان التوافق مع الإصدارات السابقة. يمكنك الاحتفاظ بمواصفات منفصلة لكل إصدار وتشغيل الاختبارات على جميع الإصدارات في وقت واحد.

زر

في هذا الدليل، ستتعرف على استراتيجيات الترقيم بالإصدارات الرئيسية الثلاث، ومقايضاتها، وكيفية تطبيق الترقيم بالإصدارات بشكل صحيح باستخدام Modern PetstoreAPI كمرجع.

لماذا تحتاج واجهات برمجة التطبيقات (APIs) إلى الترقيم بالإصدارات؟

تتطور واجهات برمجة التطبيقات. تقوم بإضافة ميزات، وإصلاح الأخطاء، وتحسين التصميمات. في بعض الأحيان، تتسبب هذه التغييرات في تعطيل العملاء الحاليين.

التغييرات المؤثرة (Breaking Changes)

التغييرات التي تؤثر على العملاء الحاليين:

1. إزالة الحقول:

// v1
{"id": "123", "name": "Fluffy", "age": 3}

// v2 (مؤثر: تم إزالة age)
{"id": "123", "name": "Fluffy"}

2. تغيير أنواع الحقول:

// v1
{"price": "19.99"}

// v2 (مؤثر: من سلسلة نصية إلى رقم)
{"price": 19.99}

3. تغيير بنية الاستجابة:

// v1 (مصفوفة مجردة)
[{"id": "123"}]

// v2 (مؤثر: كائن مغلف)
{"data": [{"id": "123"}], "pagination": {...}}

4. تغيير بنية عنوان URL:

// v1
GET /pet/123

// v2 (مؤثر: جمع)
GET /pets/123

5. تغيير المصادقة:

// v1: مفتاح API في الاستعلام
GET /pets?api_key=xxx

// v2 (مؤثر: رمز Bearer)
GET /pets
Authorization: Bearer xxx

التغييرات غير المؤثرة (Non-Breaking Changes)

التغييرات التي لا تؤثر على العملاء:

إضافة نقاط نهاية جديدة
إضافة حقول اختيارية للطلبات
إضافة حقول جديدة للاستجابات (يجب على العملاء تجاهل الحقول غير المعروفة)
إضافة معلمات استعلام جديدة
إضافة طرق HTTP جديدة للموارد الموجودة

قرار الترقيم بالإصدارات

عندما تحتاج إلى تغيير مؤثر، لديك خياران:

1. إجبار جميع العملاء على الترقية - بسيط ولكنه يعطل التكاملات الحالية

2. دعم إصدارات متعددة - عمل إضافي ولكنه يحافظ على التوافق مع الإصدارات السابقة

تختار معظم واجهات برمجة التطبيقات العامة الخيار 2. يتيح لك الترقيم بالإصدارات تطوير واجهة برمجة التطبيقات مع منح العملاء وقتًا للترحيل.

ترقيم الإصدارات في عنوان URL

يضع ترقيم الإصدارات في عنوان URL رقم الإصدار في مسار عنوان URL.

كيف تعمل؟

GET /v1/pets
GET /v2/pets

الإصدار جزء من معرف المورد. الإصدارات المختلفة هي موارد مختلفة.

الإيجابيات

1. مرئي وصريح

الإصدار موجود في عنوان URL. يمكنك رؤيته في السجلات، وسجل المتصفح، والوثائق. لا توجد رؤوس مخفية يجب تذكرها.

2. سهل الاختبار

curl https://petstoreapi.com/v1/pets
curl https://petstoreapi.com/v2/pets

يمكنك اختبار كلا الإصدارين بطلبات HTTP بسيطة.

3. يعمل مع جميع أدوات HTTP

المتصفحات، وذاكرات التخزين المؤقت، والوكلاء (proxies)، وموازنات التحميل (load balancers) ترى عناوين URL مختلفة. يمكنها توجيه كل إصدار وتخزينه مؤقتًا وتسجيله بشكل مستقل.

4. بسيط للعملاء

العملاء يغيرون عنوان URL فقط. لا توجد رؤوس مخصصة أو منطق تفاوض على المحتوى.

5. سهل الإيقاف التدريجي

يمكنك إزالة نقاط النهاية /v1 دون التأثير على /v2.

السلبيات

1. ليس REST "نقيًا"

يجادل المتخصصون في REST بأن /v1/pets/123 و /v2/pets/123 هما نفس المورد، لذا يجب أن يكون لهما نفس عنوان URL. يجب أن يكون الإصدار في الرؤوس أو تفاوض المحتوى.

2. تلوث عنوان URL

تحتوي واجهة برمجة التطبيقات الخاصة بك على مساحات عناوين URL متعددة: /v1/*، /v2/*، إلخ.

3. أصعب في ترقيم الموارد الفردية

إذا كنت ترغب في ترقيم نقطة نهاية واحدة فقط، فأنت بحاجة إلى ترقيم واجهة برمجة التطبيقات بأكملها أو إنشاء عدم اتساق.

التطبيق

الإصدار الرئيسي في عنوان URL:

/v1/pets
/v2/pets

لا تقم بتضمين الإصدارات الثانوية:

❌ /v1.2/pets (دقيق جدًا)
✅ /v1/pets (الإصدار الرئيسي فقط)

استخدم الترقيم الدلالي للإصدارات داخليًا:

v1.0.0 - الإصدار الأولي
v1.1.0 - إضافة حقول جديدة (غير مؤثرة)
v1.2.0 - إضافة نقاط نهاية جديدة (غير مؤثرة)
v2.0.0 - تغييرات مؤثرة (عنوان URL جديد: /v2)

تستخدم Modern PetstoreAPI ترقيم الإصدارات في عنوان URL مع /v1 كإصدار حالي.

ترقيم الإصدارات في الرأس (Header)

يضع ترقيم الإصدارات في الرأس رقم الإصدار في رأس HTTP مخصص.

كيف تعمل؟

GET /pets
API-Version: 1

GET /pets
API-Version: 2

يظل عنوان URL كما هو. يحدد الرأس الإصدار.

الإيجابيات

1. عناوين URL نظيفة

/pets هو نفسه لجميع الإصدارات. لا يوجد بادئة /v1 أو /v2.

2. أكثر "توافقًا مع REST"

معرف المورد (/pets/123) لا يتغير. يتغير التمثيل بناءً على الرأس.

3. ترقيم إصدارات دقيق

يمكنك ترقيم الموارد الفردية:

GET /pets
API-Version: 2

GET /orders
API-Version: 1

السلبيات

1. غير مرئي

الإصدار ليس في عنوان URL. لا يمكنك رؤيته في السجلات أو سجل المتصفح دون التحقق من الرؤوس.

2. أصعب في الاختبار

curl -H "API-Version: 1" https://petstoreapi.com/pets
curl -H "API-Version: 2" https://petstoreapi.com/pets

يجب أن تتذكر تضمين الرأس.

3. تعقيد التخزين المؤقت

يجب أن تأخذ ذاكرات التخزين المؤقت في الاعتبار رأس API-Version. تحتاج إلى Vary: API-Version في الاستجابات.

4. تعقيد العميل

يحتاج العملاء إلى منطق رأس مخصص. لا تسهل جميع عملاء HTTP هذا الأمر.

5. غموض الإصدار الافتراضي

ماذا يحدث إذا لم يرسل العميل الرأس؟ أنت بحاجة إلى افتراضي، مما يخلق سلوكًا ضمنيًا.

التطبيق

رأس مخصص:

API-Version: 1

أو استخدم رأس Accept:

Accept: application/vnd.petstore.v1+json

تضمين رأس Vary:

Vary: API-Version

يخبر هذا ذاكرات التخزين المؤقت بأخذ الرأس في الاعتبار عند التخزين المؤقت.

تفاوض المحتوى (Content Negotiation)

يستخدم تفاوض المحتوى رأس Accept مع أنواع وسائط مخصصة.

كيف تعمل؟

GET /pets
Accept: application/vnd.petstore.v1+json

GET /pets
Accept: application/vnd.petstore.v2+json

الإصدار جزء من نوع الوسائط.

الإيجابيات

1. الأكثر "توافقًا مع REST"

هذه هي الطريقة التي صمم بها REST. تمثيلات مختلفة لنفس المورد.

2. يتبع معايير HTTP

يستخدم تفاوض محتوى HTTP القياسي.

3. يدعم تنسيقات متعددة

يمكنك ترقيم الإصدارات والتنسيق في وقت واحد:

Accept: application/vnd.petstore.v1+json
Accept: application/vnd.petstore.v1+xml

السلبيات

1. معقد

يجب أن يفهم العملاء أنواع الوسائط وتفاوض المحتوى.

2. أصعب في الاختبار

curl -H "Accept: application/vnd.petstore.v1+json" https://petstoreapi.com/pets

3. دعم ضعيف للأدوات

العديد من عملاء HTTP والأدوات لا تتعامل جيدًا مع أنواع الوسائط المخصصة.

4. تعقيد التخزين المؤقت

يجب أن تأخذ ذاكرات التخزين المؤقت في الاعتبار رأس Accept. تحتاج إلى Vary: Accept.

5. إفراط في التعقيد لمعظم واجهات برمجة التطبيقات

لا تحتاج معظم واجهات برمجة التطبيقات إلى هذا المستوى من التعقيد.

التطبيق

نوع وسائط خاص بالبائع:

Accept: application/vnd.petstore.v1+json

الاستجابة:

Content-Type: application/vnd.petstore.v1+json
Vary: Accept

كيف تطبق Modern PetstoreAPI ترقيم الإصدارات؟

تستخدم Modern PetstoreAPI ترقيم الإصدارات في عنوان URL مع سياسات واضحة.

الإصدار الحالي: v1

https://petstoreapi.com/v1/pets
https://petstoreapi.com/v1/orders
https://petstoreapi.com/v1/users

جميع نقاط النهاية تقع تحت /v1.

رأس استجابة الإصدار

تتضمن كل استجابة إصدار API:

X-API-Version: 1.2.0

يظهر هذا الإصدار الدقيق (major.minor.patch) على الرغم من أن عنوان URL يظهر الإصدار الرئيسي فقط.

تحذيرات الإيقاف

عند إيقاف إصدار ما، تتضمن الاستجابات ما يلي:

Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"

Deprecation - يشير إلى أن الإصدار قد تم إيقافه
Sunset - متى سيتم إزالة الإصدار
Link - دليل الترحيل

اكتشاف الإصدارات

تعرض نقطة النهاية الجذرية الإصدارات المتاحة:

GET https://petstoreapi.com/

{
  "versions": [
    {
      "version": "v1",
      "status": "current",
      "docsUrl": "https://docs.petstoreapi.com/v1"
    }
  ]
}

الترقيم الدلالي للإصدارات (Semantic Versioning)

تتبع Modern PetstoreAPI الترقيم الدلالي للإصدارات داخليًا:

رئيسي (v1, v2) - تغييرات مؤثرة، عنوان URL جديد
ثانوي (v1.1, v1.2) - ميزات جديدة، متوافقة مع الإصدارات السابقة
تصحيح (v1.1.1, v1.1.2) - إصلاحات أخطاء، متوافقة مع الإصدارات السابقة

تظهر الإصدارات الرئيسية فقط في عناوين URL.

اختبار إصدارات API باستخدام Apidog

يساعدك Apidog على اختبار إصدارات متعددة من API.

استيراد إصدارات متعددة

استورد مواصفات OpenAPI لكل إصدار:

petstore-v1.yaml → Environment: v1
petstore-v2.yaml → Environment: v2

تشغيل الاختبارات على جميع الإصدارات

أنشئ مجموعات اختبار تعمل على كلا الإصدارين:

// اختبار v1
pm.environment.set("baseUrl", "https://petstoreapi.com/v1");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");

// اختبار v2
pm.environment.set("baseUrl", "https://petstoreapi.com/v2");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");

التحقق من السلوك الخاص بالإصدارات

اختبر أن v1 و v2 يتصرفان بشكل مختلف:

// v1 يُرجع مصفوفة مجردة
pm.test("v1 يُرجع مصفوفة", function() {
    pm.expect(pm.response.json()).to.be.an('array');
});

// v2 يُرجع كائنًا مغلفًا
pm.test("v2 يُرجع كائنًا مغلفًا", function() {
    pm.expect(pm.response.json()).to.have.property('data');
    pm.expect(pm.response.json()).to.have.property('pagination');
});

التحقق من رؤوس الإيقاف

اختبر أن الإصدارات الموقوفة تتضمن رؤوسًا مناسبة:

pm.test("الإصدار الموقوف يتضمن رؤوس", function() {
    pm.response.to.have.header("Deprecation");
    pm.response.to.have.header("Sunset");
});

استراتيجية إيقاف الإصدارات

كيفية إيقاف الإصدارات القديمة دون التأثير على العملاء.

1. الإعلان المبكر عن الإيقاف

امنح العملاء إشعارًا لمدة 6-12 شهرًا على الأقل:

Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT

2. توفير دليل الهجرة

وثّق جميع التغييرات المؤثرة وكيفية الترحيل:

Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"

3. مراقبة الاستخدام

تتبع أي العملاء ما زالوا يستخدمون الإصدارات الموقوفة:

X-API-Version: 1.2.0
X-Client-ID: abc123

اتصل بالعملاء مباشرة إذا لزم الأمر.

4. الإغلاق التدريجي

لا تقم بإزالة الإصدار على الفور:

الشهر 1-6: الإعلان عن الإيقاف
الشهر 7-9: إضافة رؤوس الإيقاف
الشهر 10-11: تقليل حدود المعدل للإصدار الموقوف
الشهر 12: إزالة الإصدار الموقوف

5. الاحتفاظ بالتوثيق

حتى بعد الإزالة، احتفظ بالتوثيق للإصدار القديم. قد يحتاج العملاء إلى الرجوع إليه.

الخاتمة

ترقيم الإصدارات في عنوان URL هو استراتيجية ترقيم إصدارات API الأكثر عملية لمعظم الفرق. إنه مرئي، سهل الاختبار، ويعمل مع جميع أدوات HTTP. ترقيم الإصدارات في الرأس وتفاوض المحتوى أكثر "نقاءً" من منظور REST ولكنهما يضيفان تعقيدًا.

تستخدم Modern PetstoreAPI ترقيم الإصدارات في عنوان URL مع /v1 كإصدار حالي، والترقيم الدلالي للإصدارات داخليًا، وسياسات واضحة للإيقاف التدريجي. يوازن هذا النهج بين البراغماتية والتصميم الجيد لواجهة برمجة التطبيقات.

استخدم Apidog لاختبار إصدارات متعددة من API، والتحقق من السلوك الخاص بالإصدار، وضمان عمليات ترحيل سلسة بين الإصدارات.

زر

الأسئلة الشائعة

هل يجب أن أستخدم ترقيم الإصدارات في عنوان URL أم في الرأس (Header)؟

استخدم ترقيم الإصدارات في عنوان URL ما لم يكن لديك سبب محدد لعدم القيام بذلك. إنه أبسط وأكثر وضوحًا وأسهل في الاختبار. ترقيم الإصدارات في الرأس أكثر "توافقًا مع REST" ولكنه يضيف تعقيدًا لا تحتاجه معظم الفرق.

كم عدد الإصدارات التي يجب أن أدعمها في وقت واحد؟

ادعم إصدارين كحد أقصى: الحالي والسابق. دعم المزيد يخلق عبئًا على الصيانة. امنح العملاء 6-12 شهرًا للترحيل، ثم قم بإزالة الإصدارات القديمة.

هل يجب أن أبدأ الترقيم من v0 أم v1؟

ابدأ بـ v1. v0 يعني عدم الاستقرار. إذا لم تكن واجهة برمجة التطبيقات الخاصة بك مستقرة بما يكفي لـ v1، فلا تنشرها علنًا بعد.

هل أحتاج إلى ترقيم كل نقطة نهاية (endpoint)؟

لا. قم بالترقيم فقط عندما تجري تغييرات مؤثرة. إذا أضفت نقاط نهاية جديدة دون تغيير الموجودة، فلست بحاجة إلى إصدار جديد.

ماذا عن الإصدارات الثانوية (minor versions) في عناوين URL؟

لا تقم بتضمين الإصدارات الثانوية في عناوين URL. استخدم /v1، وليس /v1.2. الإصدارات الثانوية متوافقة مع الإصدارات السابقة، لذا لا يحتاج العملاء إلى تغيير عناوين URL.

كيف أتعامل مع الأخطاء الخاصة بإصدار معين؟

قم بإصلاح الأخطاء في جميع الإصدارات المدعومة. إذا كان الخطأ موجودًا فقط في v1، فقم بإصلاحه في v1. لا تجبر العملاء على الترقية إلى v2 لإصلاح الأخطاء.

هل يجب أن أستخدم الترقيم الدلالي للإصدارات؟

نعم، داخليًا. تتبع إصدارات major.minor.patch، ولكن كشف الإصدارات الرئيسية فقط في عناوين URL. يمنحك هذا المرونة لإجراء تغييرات غير مؤثرة.

ماذا لو احتجت إلى ترقيم نقطة نهاية واحدة فقط؟

مع ترقيم الإصدارات في عنوان URL، ستحتاج إلى ترقيم واجهة برمجة التطبيقات بأكملها أو إنشاء عدم اتساق. هذا مقايضة. تقبل معظم الفرق ترقيم واجهة برمجة التطبيقات بأكملها من أجل البساطة.