Recommended resources
The freely available resources this lesson will direct you to.
أهلاً بك في الدرس الخامس من رحلتنا في أساسيات الأتمتة.
في الدرس السابق، قمنا بتشريح لغة الآلات الحديثة، JSON، وفهمنا كيف تُهيكَل البيانات التي تتبادلها واجهات برمجة التطبيقات (APIs). لقد تعلمنا عن أزواج المفتاح-القيمة، الكائنات، والمصفوفات. الآن، بعد أن أصبحنا قادرين على قراءة هذه اللغة، حان الوقت لنبدأ "الحوار" بأنفسنا.
درس اليوم هو نقطة الانطلاق العملية الحقيقية. سننتقل من النظرية إلى التطبيق باستخدام أداة أساسية لأي شخص يتعامل مع الـ APIs. هدفنا لهذا الدرس هو استخدام أداة Postman لإرسال طلبات API بسيطة (GET, POST). سنقوم بإرسال طلب لجلب بيانات (GET)، تماماً كما يفعل المتصفح، وسنقوم أيضاً بإرسال طلب لإنشاء بيانات جديدة (POST)، وهو ما يحدث عند إضافة منتج جديد أو تسجيل طلب في متجرك.
هذه المهارة ستحول المفاهيم المجردة عن الـ API إلى أفعال ملموسة، وستكون أداتك الرئيسية لتجربة واختبار أي API قبل بناء أي نظام أتمتة، بما في ذلك YouCan API.
1. ما هو Postman ولماذا نحتاجه؟
قبل أن نبدأ، يجب أن تعرف ما هي هذه الأداة. ببساطة، Postman هو مختبرك الخاص لتجارب الـ API. بدلاً من كتابة كود برمجي كامل فقط لتتأكد من أن API معين يعمل كما هو متوقع، يتيح لك Postman إرسال أي نوع من الطلبات، فحص الاستجابات بالتفصيل، وتصحيح الأخطاء بسهولة.
بما أن لديك خلفية في الميكاترونكس، يمكنك التفكير في Postman كأداة تشخيص متقدمة (Diagnostic Tool). بدلاً من توصيلها بنظام ميكانيكي، أنت توصلها بـ "النظام العصبي" للويب (الـ APIs) لإرسال إشارات (Requests) وقراءة الردود (Responses) للتأكد من أن كل جزء يؤدي وظيفته بشكل صحيح.
للبدء، دعنا نأخذ فكرة سريعة عن ماهية Postman. هذا المقال المترجم إلى العربية يقدم تعريفاً موجزاً ومباشراً للأداة.
اقرأ المقدمة وقسم "ما هي تفاصيل Postman?". ركز على فهم الغرض الرئيسي من الأداة.
قبل المتابعة، يرجى تحميل وتثبيت تطبيق Postman على جهازك.
2. طلب GET: كيف "تجلب" البيانات
طلب GET هو أبسط وأشهر أنواع طلبات الـ API. وظيفته واضحة من اسمه: جلب (Get) البيانات من الخادم. عندما تكتب عنوان موقع في متصفحك، فإن المتصفح يرسل طلب GET لعرض الصفحة. في عالم الـ API، نستخدمه لجلب بيانات المنتجات، الطلبات، العملاء، إلخ.
واجهة Postman الأساسية
عند فتح Postman، ستجد واجهة بسيطة ومباشرة. هذه هي المكونات الرئيسية التي سنتعامل معها اليوم:
تطبيق عملي: جلب قائمة مستخدمين
دعنا نستخدم API عام ومجاني للتجربة يسمى reqres.in. سنطلب منه قائمة المستخدمين.
Postman Tutorial #7 - HTTP Methods GET and POST in Postman
هذا الفيديو العملي سيأخذك خطوة بخطوة لإرسال أول طلب GET لك باستخدام Postman. سيريك كيف تحصل على قائمة بيانات، ثم كيف تطلب بيانات عنصر واحد فقط.
شاهد المقاطع التالية بالترتيب: من 2:08 إلى 4:19: يوضح كيفية إنشاء طلب جديد، إدخال عنوان الـ URL، وإرسال الطلب لرؤية الاستجابة الأولية. من 4:19 إلى 5:58: يوضح كيفية استخدام نقطة نهاية (endpoint) محددة (/api/users) لجلب قائمة كاملة من المستخدمين ورؤية استجابة JSON المنظمة. من 6:48 إلى 7:49: يشرح كيف تعدل الطلب لإضافة معرّف (ID) في المسار (/api/users/3) لجلب بيانات مستخدم واحد فقط.
تلخيص الخطوات لإرسال طلب GET:
- افتح تبويبة جديدة في Postman بالضغط على علامة
+. - تأكد من أن نوع الطلب المختار هو GET.
- في حقل الـ URL، أدخل العنوان التالي:
https://reqres.in/api/users. - اضغط على زر Send.
ستلاحظ في الأسفل ظهور استجابة. انظر إلى أمرين مهمين:
- Status: 200 OK: هذا الرمز يعني أن طلبك نجح.
- Body: سترى هنا بيانات JSON التي تحتوي على مصفوفة من المستخدمين، تماماً كما تعلمنا في الدرس السابق.
لجلب مستخدم واحد فقط (مثلاً، صاحب id رقم 2)، ببساطة أضف /2 إلى نهاية الـ URL ليصبح https://reqres.in/api/users/2 واضغط Send مجدداً. ستلاحظ أن الاستجابة الآن هي كائن واحد فقط وليس مصفوفة.
3. طلب POST: كيف "ترسل" أو "تنشئ" البيانات
بينما GET مخصص للقراءة، فإن POST مخصص للكتابة أو الإنشاء. عندما تملأ استمارة على موقع ويب (مثل إضافة منتج جديد في YouCan)، يتم إرسال بياناتك إلى الخادم عبر طلب POST.
الفرق الجوهري هنا هو أن طلب POST يجب أن يحتوي على "حمولة" (Payload) أو "جسم" (Body) — وهي البيانات التي تريد إرسالها. هذه البيانات تكون غالباً بصيغة JSON.
How to do API Testing with Postman
لفهم الفرق الجوهري بين GET و POST، هذا المقال يشرح نقطة مهمة.
اقرأ الفقرتين اللتين تبدآن بـ "You also select the request method..." و "For a GET request, you don’t need to specify a body...". ركز على فهم لماذا لا يحتاج GET إلى Body بينما يحتاجه POST.
تطبيق عملي: إنشاء مستخدم جديد
سنستخدم نفس الـ API (reqres.in) لإنشاء مستخدم جديد.
Postman Tutorial #7 - HTTP Methods GET and POST in Postman
الآن، لنطبق عملياً كيفية إنشاء بيانات. هذا الفيديو يكمل ما بدأناه ويشرح كيفية إعداد وإرسال طلب POST.
شاهد المقاطع التالية بالترتيب: من 8:23 إلى 9:24: يقدم مفهوم طلبات POST والحاجة إلى إرسال بيانات (Payload) في صيغة JSON. من 9:24 إلى 11:55: يوضح خطوة بخطوة كيفية إعداد طلب POST في Postman: تغيير النوع إلى POST، الذهاب إلى تبويبة Body، اختيار raw و JSON، ثم لصق البيانات. من 11:55 إلى 12:33: يعرض كيفية تفسير استجابة طلب POST الناجح (ستلاحظ أن كود الحالة مختلف).
تلخيص الخطوات لإرسال طلب POST:
- افتح تبويبة جديدة في Postman.
- غير نوع الطلب إلى POST.
- في حقل الـ URL، أدخل العنوان:
https://reqres.in/api/users. (نعم، نفس عنوان جلب القائمة، لكن بنوع طلب مختلف). - اذهب إلى تبويبة Body أسفل حقل الـ URL.
- اختر الخيار raw.
- من القائمة المنسدلة على اليمين، اختر JSON.
- في الصندوق النصي، الصق كود الـ JSON التالي:
{ "name": "Saleh Ali", "job": "Automation Developer" } - اضغط على زر Send.
الآن، انظر إلى الاستجابة:
- Status: 201 Created: هذا الكود يعني "تم الإنشاء بنجاح". إنه مختلف عن
200 OKالخاص بـ GET، وهو أكثر تحديداً. - Body: سترى بيانات المستخدم الذي أنشأته للتو، بالإضافة إلى
idوcreatedAtتم توليدهما من قبل الخادم.
اختبر فهمك!
تخيل أنك تريد إضافة منتج جديد عبر API. نقطة النهاية (Endpoint) هي POST https://api.mystore.com/products. يتطلب الـ API إرسال كائن JSON يحتوي على اسم المنتج (name) وسعره (price).
صف الخطوات التي ستتخذها في Postman لتضيف منتجاً جديداً اسمه "سماعات لاسلكية" بسعر 250.50.
أظهر الإجابة
- أفتح تبويبة جديدة في Postman.
- أضبط نوع الطلب على POST.
- أدخل الـ URL:
https://api.mystore.com/products. - أنتقل إلى تبويبة Body.
- أختار raw ثم JSON.
- أكتب كائن الـ JSON التالي في الحقل المخصص:
{ "name": "سماعات لاسلكية", "price": 250.50 } - أضغط على زر Send.
- أتفقد الاستجابة للتأكد من أن حالة الطلب هي 201 Created وأرى بيانات المنتج الجديد الذي تم إنشاؤه.
خلاصة الدرس
لقد قمنا اليوم بخطوة عملية هائلة. أنت الآن لا تفهم فقط ما هو الـ API نظرياً، بل أصبحت قادراً على التفاعل معه مباشرة.
أهم النقاط:
- Postman هو أداتك الأساسية لاختبار وتجربة الـ APIs بدون الحاجة لكتابة كود.
- طلبات GET تستخدم لجلب البيانات. كل المعلومات التي يحتاجها الخادم تكون في الـ URL.
- طلبات POST تستخدم لإنشاء بيانات جديدة. تتطلب إرسال البيانات المراد إنشاؤها في قسم الـ Body الخاص بالطلب، غالباً بصيغة JSON.
- أكواد الحالة مثل 200 OK (نجاح) و 201 Created (تم الإنشاء بنجاح) هي مؤشرات حيوية لفهم نتيجة طلبك.
الدرس القادم
لاحظت أن الـ API الذي استخدمناه اليوم (reqres.in) كان عاماً ومفتوحاً للجميع. لكن معظم الـ APIs المهمة، مثل YouCan API، ليست كذلك. لا يمكنك ببساطة إرسال طلبات إليها، لأنها تحتاج أن تعرف من أنت وهل لديك الصلاحية للقيام بذلك.
في درسنا القادم، سنتعمق في مفهوم المصادقة (Authentication) وأنواعها المختلفة مثل API Key و OAuth. هذا هو المفتاح الذي سيفتح لنا بوابة التعامل مع واجهات برمجة التطبيقات الحقيقية والمحمية.