Postman

الـPostman: أداة من Google لاختبار الـ APIs

الـPostman هي أداة بتساعدنا نختبر الـ APIs بشكل متقدم ونبعت طلبات زي (GET, POST, PUT, DELETE) ونجرب ردود الأفعال المختلفة.

لو شغال في شركة:

• هتعمل حساب على Postman باستخدام إيميل الشركة.
• بمجرد ما تسجل، هيظهرلك الـ Workspace الخاص بالشركة، وده بيكون عليه كل البروجكتس بتاعة الشركة.
• لو مش شغال في شركة، هتعمل Workspace خاص بيك وتقدر ترتب عليه البروجكتس اللي شغال عليها.

Collections:

كل مشروع عندك هيكون له Collection خاص بيه، سواءً في الشركة أو عندك شخصيًا.

Mock Servers:

لو لسه مخلصتش الـ APIs، ممكن تعمل Mock Server كحاجة تجريبية عشان الفريق اللي بيشتغل على الواجهة الأمامية (الـ Frontend) يقدر يشتغل على Dummy API بدل ما يستنى لغاية ما تخلص. كده بيبقى عنده ردود وهمية يقدر يشتغل عليها.

إنشاء Collection جديد

1. هنضغط على كلمة New، وبعد كده نختار Collection ونسميه باسم المشروع، مثلاً:

   Talabat.APIs.CompanyName

2. كل مشروع بيبقى له Collection خاص بيه، وبنقسم الـ Collection لـ Folders لكل Module عشان يبقى الكود منظم.

   • الـAdd ⇒ Folder: جوا كل فولدر هنضيف الطلبات (Requests) اللي بنحتاجها. زي مثلاً: Get Weather Forecast News.

3. هنكتب الـ Port و الـ URL الكامل، وجنبه نحط الـ Route بتاع الـ Controller عشان نوصل للـ Endpoint، زي كده:

   https://localhost:7265/api/WeatherForecast

استخدام Params

في Postman، عندنا حاجة اسمها Params، ودي عبارة عن الباراميترز اللي بنستخدمها في Query String. بيكون ليها Key و Value، ولما نبدأ نضيفها، هنلاقيها بتظهر فوق في الـ URL.

Authorization

في بعض الـ Endpoints بيحتاجوا Authorization للوصول ليها. من هنا تقدر تحدد لو كان الـ Endpoint محتاج صلاحيات معينة للوصول.

الـHeader و Body: شرح كل واحدة

• Header:
  • دي بتبقى بيانات إضافية ممكن نبعتها مع الطلب (Request)، زي الـ Authorization Token، أو معلومات عن نوع البيانات (Content-Type).
• Body:
  • ده بيكون محتوى الطلب، وبنستخدمه خصوصًا في الطلبات اللي فيها بيانات محتاجين نبعتها، زي طلبات الـ POST أو PUT. ممكن نستخدمه نرفع بيانات JSON، أو نصوص، أو حتى ملفات.

إرسال الطلب وتشغيل التطبيق

• عشان تعمل Send لازم يكون التطبيق (API) شغال، عشان الـ Postman يقدر يتواصل معاه.
• بعد ما تبعت الطلب، هيرجعلك رد من الـ API، هيكون فيه:
  • Status Code: اللي بيوضح هل الطلب اتنفذ بنجاح ولا لأ.
  • Time: الزمن اللي استغرقه الطلب لغاية ما رجع الرد.

دعوات ودعم الفريق

• ممكن تعمل Invite لحد للـ Workspace، وكده أي حد تاني هيقدر يشوف نفس الـ Collections والبروجكتس.
• كمان ممكن تعمل Invite لمشروع معين بس.
• تقدر كمان تعمل Export للـ Collection وتنقله لشخص تاني أو تحتفظ بنسخة احتياطية.

Variables

في Postman، تقدر تستخدم Variables (المتغيرات) عشان تسهل عليك تغيير القيم المشتركة في أكتر من طلب، وتقدر تختار إنها تكون Local (خاصة بالـ Collection أو البيئة اللي شغال فيها) أو Global (لكل الـ Workspace).

أنواع المتغيرات في Postman

1. Global Variables (متغيرات عامة):

   • دي متغيرات تقدر تستخدمها في كل الـ Workspace بدون ما تحتاج تضيفها في كل Collection أو بيئة (Environment).
   • مناسبة لما تكون عايز قيمة تستخدمها في أكتر من مشروع، زي API Key مشترك أو URL عام.

2. Environment Variables (متغيرات البيئة):

   • دي متغيرات بتكون مخصصة لبيئة معينة زي (Local, Staging, Production)، ودي بتبقى خاصة بكل بيئة على حدة.
   • بتستخدمها لما تحتاج تغير القيم بين بيئات مختلفة. مثلاً، URL في بيئة الـ Local هيكون مختلف عن بيئة الـ Production، فبتعمل متغير لكل بيئة وتغيره حسب الحاجة.

3. Collection Variables (متغيرات خاصة بـ Collection):

   • دي بتبقى خاصة بكل Collection على حدة، وبتساعدك لو عندك قيمة ثابتة لمجموعة من الطلبات داخل نفس الـ Collection.
   • مفيدة لو عندك بيانات مشتركة تخص مشروع معين وعايز تتجنب تكرار القيم جواه.

4. Local Variables (متغيرات محلية):

   • دي بتكون خاصة بالـ Request فقط، بتكون قصيرة المدى يعني بتشتغل في نفس الـ Request، وبعدها بتختفي.
   • مناسبة لو عندك بيانات مؤقتة مش هتستخدمها كتير، زي نتائج حساب معين في نفس الطلب.

---

خطوات إضافة المتغيرات في Postman:

1. لإضافة متغيرات عامة (Global Variables):

   • روح لـ Settings من خلال الضغط على الأيقونة فوق.
   • اختار Globals، وبعدها اضغط على Add لإضافة متغير جديد، وحدد Key وValue للمتغير.
   • هتقدر تستخدمه في أي مكان في الـ Workspace بالشكل: {{variable_name}}.

2. لإضافة متغيرات البيئة (Environment Variables):

   • من القائمة الجانبية، اختار Environments.
   • اضغط على New Environment واعمل بيئة جديدة زي (Local, Staging, Production).
   • أضف المتغيرات بالـ Key وValue حسب كل بيئة.
   • بعد كده، تقدر تختار البيئة اللي شغال عليها من قائمة البيئات فوق على اليمين.

3. لإضافة متغيرات لـ Collection:

   • اضغط على Collection اللي عايز تضيف فيها المتغيرات.
   • من إعدادات الـ Collection، اختار Variables وأضف المتغيرات اللي عايزها بالـ Key وValue.

4. لإضافة متغيرات محلية:

   • المتغيرات المحلية بتقدر تضيفها مباشرة في الـ Script بتاع الـ Request نفسه، سواءً في Pre-request Script أو Tests باستخدام:

     pm.variables.set("variable_name", "value");

   • بعد كده، تقدر تستخدم المتغير في نفس الطلب بالشكل: {{variable_name}}.

---

مثال عملي:

لو عندك URL خاص ببيئة الـ Local وبيئة الـ Production، ممكن تعمل التالي:

1. أضف متغير بيئة base_url، خلي القيمة في الـ Local تكون:

   http://localhost:5000
   

   وفي الـ Production خليها:

   https://api.company.com
   

2. استخدمه في الـ Request زي كده:

   {{base_url}}/api/WeatherForecast
   

بكده، تقدر تبدل بين البيئات بسهولة من غير ما تغير كل URL في الطلبات، وده بيسهل الشغل ويوفر وقت كتير في التعديل.