عند تصميم واجهات برمجة التطبيقات (APIs)، يجب جعلها قابلة للتكرار لضمان متانتها وموثوقيتها وقدرتها على تحمل الأخطاء. تُعتبر العملية قابلة للتكرار، لكن تكرارها سيؤدي دائمًا إلى نفس النتيجة. على سبيل المثال، زر المصعد قابل للتكرار. مهما ضغطت على زر المصعد نفسه، سيصل المصعد إلى الطابق المحدد مرة واحدة. يجب أن تعمل واجهات برمجة التطبيقات (APIs) الخاصة بك بنفس الطريقة.

في هذه المقالة، سنتناول كيفية بناء واجهات برمجة تطبيقات (APIs) متعددة الإمكانيات في ASP.NET Core، مع أمثلة برمجية مناسبة لتوضيح المفاهيم التي تناولتها. لاستخدام أمثلة الأكواد الواردة في هذه المقالة، يجب تثبيت Visual Studio 2022 على نظامك. إذا لم تكن لديك نسخة منه، يمكنك تنزيله من هنا .

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

تضمن واجهات برمجة التطبيقات (APIs) المتماثلة أن تُعطي الطلبات المكررة نفس النتيجة. على سبيل المثال، تُعدّ أساليب HTTP GET وHEAD وOPTIONS وTRACE متماثلة لأنها لا تُعدّل حالة المورد على الخادم، بل تقوم بجلب بيانات تعريف المورد ذات الصلة أو تمثيلها.

دعونا نفهم أهمية تعدد استخدامات واجهة برمجة التطبيقات (API) بمثال. في تطبيقات عربات التسوق التقليدية، غالبًا ما يحتاج المستخدم إلى استدعاء واجهة برمجة التطبيقات لإنشاء طلب جديد. في حال نجاح الطلب، يُفترض أن يتلقى المستخدم تأكيدًا. مع ذلك، قد تمنع مشكلة في الشبكة المستخدم من استلام التأكيد، حتى لو أرسل طلب واجهة برمجة التطبيقات. في هذه الحالة، قد يرغب المستخدم في إعادة إنشاء الطلب نفسه، أي إعادة محاولة استدعاء واجهة برمجة التطبيقات نفسه، لأنه لم يتلقَّ تأكيدًا بعد الطلب السابق لإنشاء طلب جديد.

ماذا لو تم إنشاء الطلب نفسه أكثر من مرة؟ 

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

فهم القدرة على التكرار في طرق HTTP

لاحظ أن طريقتي HTTP POST وHTTP PATCH ليستا متماثلتين . أما طرق HTTP GET وHEAD وPUT وDELETE فهي متماثلة بطبيعتها.

• HTTP GET: عملية HTTP GET هي الطريقة الأكثر استخدامًا في HTTP. تسترجع هذه العملية البيانات من الخادم دون أن تُغيّر حالة المورد. لذا، فإن استدعاء طريقة HTTP GET يكون غير فعال.
• HTTP HEAD: تُستخدم طريقة HTTP HEAD لاسترجاع البيانات الوصفية لمورد. تُستخدم هذه الطريقة عادةً لتحديد ما إذا كان المورد متاحًا على الخادم. في حال وجود المورد، يُرجع استدعاء طريقة HTTP HEAD حجم المورد وتاريخ آخر تعديل له. على عكس طريقة HTTP GET، لا تُرجع طريقة HTTP HEAD نص الرسالة كجزء من الاستجابة.
• HTTP PUT: تستخدم طريقة HTTP PUT لتحديث البيانات الموجودة على الخادم. تذكر أن هذه العملية ستُغيّر حالة المورد في المرة الأولى فقط. أما عمليات PUT اللاحقة فلن تُغيّر حالة المورد، بل ستُستبدل الحالة بنفس المُدخلات. على سبيل المثال، إذا حدّثت سجلًا في قاعدة بيانات، فيجب أن يتحقق التحديث أولًا من وجود السجل. إذا كان موجودًا، فيجب استبدال البيانات المُخزّنة في قاعدة البيانات بالبيانات الجديدة. مع ذلك، إذا أجريتَ استدعاءات متعددة لنفس طريقة API بنفس المُدخلات، فستبقى البيانات المُخزّنة في قاعدة البيانات كما هي.
• حذف HTTP: يمكنك حذف مورد عدة مرات، ولكن الحذف الأول فقط هو الذي سيُغيّر حالة النظام. ولأن استدعاء عملية حذف HTTP واحدة أو أكثر يُعطي نفس النتيجة، فإن هذه الطريقة لا تُطبّق. إذا حذفت موردًا غير موجود، فيجب أن تُعيد الطريقة رسالة تُفيد بأنه قد حُذف المورد أو لم يُعثر عليه.
• HTTP POST: تُستخدم طريقة HTTP POST لإرسال البيانات إلى الخادم للمعالجة. ولأن عملية POST تُنشئ موردًا جديدًا على الخادم، فهي ليست عمليةً تلقائية. قد تُؤدي استدعاءات POST المتعددة إلى موارد جديدة متعددة.
• HTTP PATCH: تُستخدم طريقة HTTP PATCH لتعديل مورد على الخادم دون تغيير المورد بأكمله. هذه الطريقة ليست مثالية، لأن طلبات HTTP PATCH المتكررة قد تُغيّر حالة المورد بشكل متكرر. على سبيل المثال، إذا طلبتَ HTTP PATCH لتقليل كمية عنصر في المخزون، فسيقلّ المخزون المتاح من هذا العنصر مع كل تكرار للطلب.

إنشاء مشروع ASP.NET Core Web API في Visual Studio 2022

لإنشاء مشروع واجهة برمجة تطبيقات ويب ASP.NET Core 9 في Visual Studio 2022، اتبع الخطوات الموضحة أدناه.

1. قم بتشغيل Visual Studio 2022 IDE.
2. انقر فوق "إنشاء مشروع جديد".
3. في نافذة "إنشاء مشروع جديد"، حدد "ASP.NET Core Web API" من قائمة القوالب المعروضة.
4. انقر فوق التالي.
5. في نافذة "تهيئة مشروعك الجديد"، حدد اسم المشروع الجديد وموقعه. يمكنك أيضًا تفعيل خيار "وضع الحل والمشروع في نفس المجلد"، حسب تفضيلاتك.
6. انقر فوق التالي.
7. في نافذة "معلومات إضافية" المعروضة لاحقًا، حدد ".NET 9.0 (دعم المصطلحات القياسية)" كإصدار إطار العمل، وتأكد من تحديد مربع "استخدام وحدات التحكم". سنستخدم وحدات التحكم في هذا المشروع.
8. في نافذة "معلومات إضافية"، اترك "نوع المصادقة" مضبوطًا على "بدون" (الإعداد الافتراضي)، وتأكد من عدم تحديد مربعات الاختيار "تمكين دعم واجهة برمجة التطبيقات المفتوحة" و"التهيئة لـ HTTPS" و"تمكين Docker". لن نستخدم أيًا من هذه الميزات هنا.

بشكل عام، يُنصح بجعل واجهات برمجة التطبيقات (APIs) لديك متعددة الإمكانيات لمنع تكرار الطلبات وإعادة المحاولة من وضع تطبيقك في حالة غير صحيحة. بمعنى آخر، تساعد واجهات برمجة التطبيقات متعددة الإمكانيات في جعل تطبيقك أكثر متانة وموثوقية وتحملًا للأخطاء.