مقدمة في web APIs in ASP.NET Core [RESTful pattern]

-

كيفية إنشاء واجهات برمجة تطبيقات الويب في ASP.NET Core [نمط RESTful] 


ما هي REST API؟

اليوم يشهد العالم تزايد كبير جدا في التطبيقات وبأنواع مختلفة للعملاء (mobile apps, browser-based SPAs, desktop apps, IOT apps, ... الخ)، لذلك كان لا بد من إيجاد طرق أفضل لنقل البيانات من servers إلى clients، بغض النظر عن التكنولوجيا وserver stacks.

REST APIs حل هذه المشكلة. REST تعني representational state transfer. تعتمد REST APIs على HTTP وتوفر للتطبيقات القدرة على الاتصال باستخدام تنسيق JSON خفيف الوزن lightweight JSON. يتم تشغيلها على خوادم الويب web servers.


يتكون REST من الكيانات التالية:


الموارد Resource: الموارد هي كيانات entities يمكن التعرف عليها بشكل فريد (على سبيل المثال: data from a database أو images أو أي بيانات غيرها يمكن استخدامها).

  1. Endpoint: هي عبارة عن resource يمكن الوصول اليها من خلال URL identifier.
  2. HTTP method: هي نوع الطلب الذي يرسله العميل client إلى server. حيث يجب ان تتبع العمليات التي نقوم بها على resource على هذه الطريقة.
  3. HTTP header: هو عبارة عن قيمة معينة إضافية تُستخدم لمشاركة معلومات إضافية بين العميل client والخادم server ، مثل:
    • نوع البيانات التي يتم إرسالها إلى الخادم (JSON، XML).
    • نوع التشفير encryption الذي يدعمه العميل.
    • رمز متعلق بالمصادقة Authentication-related token.


يستخدم في هذا REST APIs تنسيق البيانات بشكل JSON هو تنسيق شائع لإرسال البيانات واستلامها من خلال REST APIs.


يعد إنشاء واجهات برمجة تطبيقات الويب API في ASP.NET Core أمرًا سهلاً للغاية. تقوم بإنشاء وحدات تحكم controllers  بها 3 أشياء:


  1. يجب إضافة السمة [ApiController] في بداية API ، والتي تعني أن وحدة التحكم controller ستخدم استجابات HTTP API Responses
  2. يجب أن يتم اشتقاقها من class  ControllerBase  بدلاً من Controller class
  3. يجب تطبيق  attribute routing  (توجيه السمة)  [Route("someUrl/[controller]")]
  4. بناء على ما سبق ستكون Controller   في Web API كما يلي:

[ApiController] 

[Route("someURL/[controller]")] 

public class ExampleController : ControllerBase


ما هي Web API ؟

واجهة برمجة تطبيقات الويب Web API هي طريقة برمجة يمكن الوصول إليها عبر الويب باستخدام بروتوكول HTTP. على سبيل المثال، يمكننا الحصول على حالة الطقس عن طريق استدعاء API خاص بحالة الطقس من المواقع التي توفر هذه الخدمة. يمكن إنشاء Web API في أي تقنية مثل ASP.NET Core وJAVA وPython وما إلى ذلك. ويمكن أيضًا استخدامها في أي تقنية. هذا الامر يجعل Web APIs خيارًا مثاليًا لبناء وتطوير التطبيقات، حيث يسهل عملية التواصل بين التطبيقات
يتمثل عمل Web API في نقل البيانات عبر الإنترنت. يتم نقل البيانات باستخدام طرق طلب HTTP Protocol’s المعروفة باسم HTTP Verbs. 
HTTP Verbs الأكثر استخدامًا هي GET و POST و PUT و PATCH و DELETE. يتم استخدام تنسيقات ملفات JSON و XML بواسطة Web APIS لنقل البيانات عبر الإنترنت.

الفرق بين "ControllerBase" و  "Controller" 

يجب ألا تنشئ وحدة تحكم Web API من خلال الاشتقاق من Controller class لأن Controller class مشتقة من ControllerBase class وتضيف دعمًا ل views، لذلك فهي مخصصة للتعامل مع صفحات الويب. هناك استثناء لهذه القاعدة: إذا كنت تخطط لاستخدام نفس controller لكل من views و web APIs ، فاشتقها فقط من Controller class. 
فيما يلي طريقة الاشتقاق من ControllerBase class (يسمى هذا الكود skeleton )
[ApiController] 
[Route("api/[controller]")] 
public class ReservationController : ControllerBase { ... }

يوفر ControllerBase class  العديد من الخصائص والأساليب المفيدة للتعامل مع طلبات HTTP. منها :

الاسم 
الوصف
Ok
يعيد الكود 200 والذي يعني نحاج العملية
NotFound
يعيد الكود 404 والذي يعين غير موجود
BadRequest
يعيد الكود 400 والذي يعني خطأ

  1. ما هي ApiController attribute؟

    كما ذكرنا سابقا يجب تطبيق attribute [ApiController]  في وحدة تحكم Web API ، وذلك بهدف إضافة إمكانيات الى API حتى يتمكن من أداء مهام محددة ل API . هذه المهام هي:

    1. الاستجابة ل Attribute Routing.
    2. يقوم تلقائيًا بتشغيل HTTP 400 response عندما لا يتم العثور على resource على server.
    3. يحدد الموقع الذي توجد فيه قيم parameter . وهذه المواقع هي  [FromBody] ، [FromForm] ، [FromHeader] ، [FromQuery] ، [FromRoute] Attriubtes.
    4. عند استخدام [FromForm] attribute لإرسال parameter  في action method’s ، يتم استنتاج نوع محتوى content type للبيانات بشكل multipart/form-data.
    5. يعمل Web API على إرجاع الخطأ في حال حدوثه مستندًا إلى مواصفات RFC 7807. يتيح ذلك لواجهة برمجة تطبيقات الويب المصممة بتقنيات مختلفة مثل Java و Ruby و ASP.NET Core وغيرها من التواصل مع بعضها البعض دون أي مشكلة.