انتقل إلى المحتوى الرئيسي

الوحدة 6 · اختبار واجهات البرمجة

HTTP والطرق ورموز الحالة

نموذج الطلب والاستجابة الذي يقوم عليه كل اختبار لواجهات البرمجة.

نحو 11 دقيقة قراءة و10 دقيقة تطبيق (تقديرات)

جارٍ تحميل التقدم…

اقرأ

أهداف التعلّم

  • قراءة طلب HTTP واستجابته.
  • شرح الغرض من GET وPOST وPUT وPATCH وDELETE، وأيها آمن أو متساوي الأثر عند التكرار.
  • تفسير فئات رموز الحالة الرئيسية.

الشرح

يتكون طلب واجهة البرمجة من طريقة وعنوان URL وترويسات، وأحياناً جسم. وتتكون الاستجابة من رمز حالة وترويسات، وغالباً جسم — بصيغة JSON في الأغلب. وترسل اختبارات واجهات البرمجة الطلبات مباشرة، مما يجعلها أسرع وأدق من المرور عبر واجهة المستخدم.

الطريقةالاستخدام المعتادآمنةمتساوية الأثر
GETقراءة موردنعمنعم
POSTإنشاء شيء أو تنفيذ إجراءلالا
PUTاستبدال موردلانعم
PATCHتعديل جزء من موردلاليس بالضرورة
DELETEحذف موردلانعم

«آمنة» تعني أن الطلب لا يُقصد به تغيير أي شيء على الخادم. و«متساوية الأثر» تعني أن إرساله مرتين له الأثر المقصود نفسه لإرساله مرة واحدة — وهذا مهم عندما يعيد العملاء المحاولة بعد انتهاء المهلة.

  • 2xx نجاح — 200 OK، و201 Created (غالباً مع ترويسة Location)، و204 No Content.
  • 3xx إعادة توجيه — المورد في مكان آخر.
  • 4xx خطأ من العميل — 400 Bad Request، و401 Unauthorized، و403 Forbidden، و404 Not Found، و409 Conflict، و422 Unprocessable Content، و429 Too Many Requests.
  • 5xx خطأ في الخادم — 500 Internal Server Error، و503 Service Unavailable. ورمز 5xx يسببه إدخال المستخدم خطأ برمجي: يجب أن يرفض الخادم الإدخال السيئ برمز 4xx.

مثال: قراءة قائمة المنتجات

توضيحي — ليس عنوان API يعمل فعلاً.

GET /v1/products?category=ceramics HTTP/1.1
Host: api.dar-al-souq.example
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    { "id": "incense-burner", "price": "6.500", "currency": "OMR" },
    { "id": "coffee-cups",    "price": "8.250", "currency": "OMR" },
    { "id": "serving-bowl",   "price": "12.000", "currency": "OMR" }
  ],
  "count": 3
}
توضيحي: واجهة برمجة وهمية للمتجر التدريبي (نطاق ‎.example لا يشير إلى أي خادم).

أخطاء شائعة

  • اعتبار أي رمز 200 نجاحاً دون قراءة الجسم.
  • قبول 500 لإدخال غير صالح على أنه «متوقع».
  • إعادة طلبات POST غير متساوية الأثر في الاختبارات دون التحقق من التكرار.

جرّب

تدرّب على ما قرأته للتو. تُفحص الإجابات هنا، ولا يُقيَّم شيء علناً ولا يُحتسب في ساحة الأخطاء.

تمرين

طلب POST /v1/orders ببيانات صالحة يُنشئ طلب شراء. ما الاستجابة الأنسب؟

اختر إجابة واحدة.

راجع

اختبر نفسك — يجب أن تكون الآن قادراً على:

  • قراءة طلب HTTP واستجابته.
  • شرح الغرض من GET وPOST وPUT وPATCH وDELETE، وأيها آمن أو متساوي الأثر عند التكرار.
  • تفسير فئات رموز الحالة الرئيسية.

تدرّب في مختبر الجودة

مراجع

تابع

عندما تكون مستعداً، ضع علامة الإكمال على الدرس في خطوة «جرّب» ثم انتقل إلى التالي.

يُوسم بأنه مقروء عندما تصل إلى نهاية الدرس.