C# Academy · درس

استراتيجيات إصدار إصدارات API

أصدروا الإصدارات عبر عنوان URL والترويسة وسلسلة الاستعلام

استراتيجيات إصدار إصدارات API درس مجاني في C# Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في C# Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة C# Academy 4 دروس في المجموع.

لماذا نُصدر نسخًا من API؟

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

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

إصدار النسخ في مسار URL

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

GET /api/v1/products
GET /api/v2/products

إصدار النسخ في سلسلة الاستعلام

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

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

إصدار النسخ في الترويسة

تحمل ترويسة طلب مخصصة الإصدار، مما يحافظ على نظافة عنوان URL. أما الجانب السلبي فهو أن الإصدار لا يظهر في شريط عناوين المتصفح، ويصعب اختباره يدويًا.

GET /api/products
X-Api-Version: 2.0

إصدار النسخ في نوع الوسائط

يُسمى هذا أيضًا تفاوض المحتوى. ويُضمَّن الإصدار في نوع وسائط ترويسة Accept. وهو الخيار الأكثر توافقًا مع REST، لكنه الأقل سهولة في الاكتشاف.

GET /api/products
Accept: application/json;v=2.0

مقارنة الاستراتيجيات

توازن كل استراتيجية بين سهولة الاكتشاف ونظافة عناوين URL:

مسار URL: الأسهل اكتشافًا، لكنه يزدحم بعناوين URL.
سلسلة الاستعلام: عناوين URL مستقرة وقيم افتراضية سهلة.
الترويسة: عناوين URL نظيفة، لكنها مخفية عن المتصفحات.
نوع الوسائط: أنقى تطبيق لـ REST، لكنه الأصعب استخدامًا.

// Many teams pick URL path for public APIs

الإصدار الدلالي لواجهات API

تكون إصدارات API عادةً رئيسية فقط (v1 وv2). فاحتفظ بالإصدارات الثانوية للتغييرات الإضافية غير المتوافقة، التي يمكن للعملاء القدامى تجاهلها.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

الإهمال

لا تزل إصدارًا قديمًا فجأة. علّمه بأنه مهمل، وأعلن تاريخ إيقافه، وأبلغ العملاء بذلك عبر الترويسات.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

الإصدار الافتراضي

حدّد ما يحدث عندما لا يرسل العميل أي إصدار. تشمل الخيارات الشائعة افتراض الإصدار الأحدث، أو افتراض v1، أو رفض الطلب. ويؤدي تحديد ذلك بوضوح إلى تجنب المفاجآت.

// Strategy: unversioned request -> treat as v1.0

إصدار العناصر الصحيحة

أصدر العقد (المسارات وأشكال الطلبات والاستجابات)، وليس تفاصيل التنفيذ الداخلية. ويمكن لنقطة نهاية v2 مشاركة معظم منطق العمل مع v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

دمج الاستراتيجيات

يمكن لمكتبة إصدار النسخ في ASP.NET Core قراءة الإصدار من عدة مصادر في الوقت نفسه، مما يتيح للعملاء اختيار المصدر الأنسب لهم. ستضبط ذلك في الخطوة التالية.

// Accept version from URL OR header OR query

اختبار سريع

اختبر فهمك لاستراتيجيات إصدار النسخ.

مراجعة

لقد استعرضت استراتيجيات إصدار نسخ API:

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

التالي: ضبط Asp.Versioning في ASP.NET Core.

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

هل درس «استراتيجيات إصدار إصدارات API» مجاني؟

نعم — نص درس «استراتيجيات إصدار إصدارات API» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة C# Academy، انتقل إلى CoddyKit PRO. تتضمن دورة C# Academy 4 دروس في المجموع.

ماذا ستتعلم في «استراتيجيات إصدار إصدارات API»؟

أصدروا الإصدارات عبر عنوان URL والترويسة وسلسلة الاستعلام تتمرن على C# Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ C# Academy؟

لا تُشترط خبرة سابقة. C# Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «استراتيجيات إصدار إصدارات API»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس C# Academy هذا؟

نعم. كل درس في C# Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى C# Academy