اختبار واجهات برمجة التطبيقات (APIs) والتفاعل معها بسهولة باستخدام Postman

في عالم تعتمد فيه المواقع والتطبيقات الثابتة بشكل متزايد على واجهات برمجة التطبيقات (APIs) التي تتم صيانتها بشكل منفصل، قد يكون من الصعب فهم كيفية عمل هذه الواجهات بمجرد التفاعل معها عبر المتصفح. فكيف يمكننا استخدام أداة Postman لاختبار واجهات برمجة التطبيقات الموجودة لدينا وفهم آلياتها بشكل أفضل؟

ما هو Postman؟

يُعد Postman أداة قوية ومتكاملة تمكن الفرق من اختبار واجهات برمجة التطبيقات (APIs) بشكل موثوق باستخدام إعدادات سهلة الاستخدام. يأتي مزودًا بمجموعة واسعة من الميزات التي تتوقعها عند التعامل مع APIs، بما في ذلك المصادقة (Authentication)، وتعيين الرؤوس (Headers)، وتخصيص حمولة البيانات (Payload)، والعديد من الخيارات الأخرى التي تقلل من تعقيد استخدام API.

لا يقتصر استخدام Postman على الاختبار فحسب، بل يمتد ليشمل جوانب متعددة من العمل مع APIs لمختلف أعضاء الفريق. قد يرغب مدير المشروع في التحقق من سير الأمور بشكل صحيح، أو قد يجد سهولة في إجراء تغيير مباشر عبر API. كذلك، يحتاج مهندس ضمان الجودة (QA Engineer) للتأكد من أن كل شيء لا يزال يعمل بكفاءة، أو قد يرغب المطور في إجراء تغييرات نشطة أثناء العمل على API نفسه.

أحد أفضل جوانب Postman هو توفيره لميزات التعاون. تتضمن الطبقة المجانية تصدير واستيراد مجموعات من طلبات API المحفوظة، بالإضافة إلى إنشاء روابط مشاركة. إذا كنت جزءًا من فريق، فإن هناك طبقات مدفوعة تتيح لك مزامنة مجموعاتك (Collections) لضمان حصول الجميع على أحدث وأحدث إصدار منها.

ماذا سنتعلم في هذا الدليل؟

سنتناول في هذا الدليل مثالين مختلفين لواجهات برمجة التطبيقات (APIs) لتغطية مفاهيم Postman الأساسية. أولاً، سنتعامل مع بعض طلبات HTTP البسيطة باستخدام واجهة Pokémon API العامة. ثم سنستخدم واجهة Yoda Translator API لتوضيح كيفية إجراء طلبات HTTP محددة.

بمجرد فهمنا لأساسيات العمل، سننتقل إلى استخدام واجهة Lord of the Rings API لنتعلم كيفية عمل المصادقة (Authentication) مع APIs. لهذا الجزء، ستحتاج إلى التسجيل للحصول على حساب مجاني للحصول على مفتاح API Key.

الجزء 0: البدء وإعداد Postman

قبل البدء، ستحتاج إلى تثبيت Postman لتتمكن من متابعة هذا الدليل. الخبر السار هو أن Postman متاح مجانًا لأنظمة Mac و Windows و Linux، لذا يجب أن تكون قادرًا على العثور على إصدار يناسبك.

• احصل على Postman: https://www.postman.com/downloads/

بمجرد التنزيل، اتبع إرشادات التثبيت القياسية، ثم افتح التطبيق، وسنكون جاهزين للانطلاق!

الجزء 1: مقدمة إلى Postman ومفاهيمه الأساسية

عند فتح Postman لأول مرة، ستظهر لك لوحة إطلاق (Launchpad) تحتوي على العديد من الخيارات للبدء.

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

الطلبات (Requests)

الطلب هو بالضبط ما يوحي به اسمه؛ إنه طلب API محدد. سيكون هذا نوعًا واحدًا من الطلبات، سواء كان طلب GET أو POST إلى نقطة نهاية (Endpoint) معينة. ستحتاج إلى إنشاء طلبات جديدة لكل نوع من نقاط النهاية، مما يتيح لك التنقل بينها عند الاختبار.

المجموعات (Collections)

المجموعة هي مجموعة من الطلبات. هذا مفيد لتنظيم طلباتك في مجموعات مختلفة. يمكن أن يكون هذا بسيطًا مثل واجهتي API مختلفتين تمامًا (مثل Twitter مقابل Slack)، أو يمكن أن تكون مجموعتين مختلفتين من APIs لواجهة API واحدة (مثل Twitter Tweets API مقابل Twitter Accounts API).

المصادقة (Authorization)

المصادقة هي كيفية التحقق من صحة الطلبات مع واجهة API، سواء كان ذلك بواسطة شخص يقوم بالطلب أو بواسطة جهاز يقوم بهذا الطلب نيابة عنك. يأتي هذا عادة في شكل مفتاح API Key يمكن أن يكون قيمة ثابتة مخصصة لحسابك أو يتم إنشاؤه ديناميكيًا باستخدام أدوات مثل OAuth.

البيئات (Environments)

تتيح لك البيئات تهيئة نقاط النهاية الخاصة بك لاستخدام متغيرات محددة تجعل من السهل استخدام نفس نقاط النهاية بين بيئات مختلفة. على سبيل المثال، قد يكون لديك نفس نقطة النهاية /profile في كل من بيئات الإنتاج (Production) والتطوير (Development)، ولكن لديهما نطاقات (Domains) مختلفة. تتيح لك البيئات إدارة طلب واحد باستخدام نطاق متغير.

مساحات العمل (Workspaces)

لن نتعمق كثيرًا في مساحات العمل في هذا المقال، ولكنها تتيح لك إدارة وتنظيم مجموعات مختلفة من المجموعات. تخيل أنك تريد استخدام Postman للعمل ومشروع شخصي، فقد يكون لديك مساحة عمل للعمل (Work workspace) بالإضافة إلى مساحة عمل شخصية (Personal workspace). لأغراض هذا المقال، سنغطي الطلبات (Requests)، والمجموعات (Collections)، والمصادقة (Authorization).

الجزء 2: إنشاء طلب GET للحصول على معلومات حول Squirtle

الآن بعد أن أصبح لدينا فهم أفضل للمصطلحات المختلفة، دعنا ننشئ طلبًا فعليًا. في الجزء العلوي الأيسر من واجهة المستخدم، يجب أن ترى زرًا برتقاليًا مكتوبًا عليه New. انقر فوقه ثم حدد Request.

قبل أن ننتقل إلى الطلب نفسه، فإنه يتطلب بعض الأشياء. أول شيء مطلوب هو اسم. سنبدأ بطلب معلومات حول البوكيمون Squirtle، لذا دعنا نسميه “Pokémon - Squirtle“. يتطلب أيضًا مجموعة، لذا انقر فوق Create Collection ودعنا نسمي المجموعة “My Favorite Pokémon“.

انقر فوق زر علامة الصح البرتقالي بجوار اسم المجموعة ثم اضغط على Save. في هذه المرحلة سيكون لدينا طلب جديد، لذا دعنا نبني هذا الطلب. هناك شيئان سنحتاج إلى ملئهما أولاً لطلبنا الأول:

• نوع الطلب (Request type): GET، POST، PUT، إلخ – سنستخدم GET.
• عنوان URL للطلب (Request URL): نقطة النهاية لطلب API الخاص بك – لطلبنا سنستخدم https://pokeapi.co/api/v2/pokemon/squirtle/.

وبمجرد التأكد من صحة هذه البيانات، يمكنك ببساطة النقر على زر Send الأزرق على اليمين وقد نجحنا في إجراء طلبنا الأول!

نحصل على الفور على بعض الأشياء التي يمكننا رؤيتها:

• الجسم (Body): في الأسفل يجب أن نرى الآن جسم الاستجابة لطلب API. بالنسبة لواجهة Squirtle API الخاصة بنا، يجب أن يكون لدينا كائن JSON ببيانات مثل abilities و base_experience و forms.
• الحالة (Status): على اليمين، يجب أن نرى رمز حالة HTTP. “200 Ok” علامة جيدة وتعني أنه كان ناجحًا!
• الوقت (Time): ببساطة المدة التي استغرقها الطلب للانتهاء.
• الحجم (Size): الحجم بالكيلوبايت (في مثالنا) لبيانات الاستجابة.

يمكنك أيضًا التمرير فوق Status و Time و Size للحصول على نظرة أكثر تفصيلاً لكل خيار. لقد أجرينا طلبنا الأول! شيء واحد يجب ملاحظته قبل الانتقال هو أن طلبنا يبدو وكأنه في علامة تبويب متصفح. إذا انتهينا من هذا الطلب بالذات، يمكننا إغلاق علامة التبويب والنقر على Save للتأكد من أن جميع تغييراتنا موجودة للمرة القادمة!

الجزء 3: تنظيم الطلبات في مجموعات (Collections) باستخدام PokéAPI

الآن بعد أن أنشأنا طلبًا، دعنا ننشئ مجموعة منهم. تقنيًا، كان علينا بالفعل إنشاء مجموعة جديدة للجزء 2، لكننا سننشئ واحدة جديدة لنتعلم كيفية عمل المجموعات نفسها. في الجزء العلوي الأيسر من واجهة المستخدم، انقر فوق الزر New البرتقالي مرة أخرى وحدد Collection.

على غرار الطلب، يطلب اسمًا لذا دعنا نسمي هذا “PokéAPI“. اختياريًا يمكنك إضافة وصف، ثم انقر فوق Create في الأسفل.

على اليسار، سترى الآن مجموعتك. يمكنك تحديد وتوسيع المجلد حيث سنعمل معه. قبل إضافة طلب، تحتوي واجهة PokéAPI على أنواع مختلفة من الطلبات، لذلك من المنطقي تنظيمها بشكل أكثر شمولاً. لذا دعنا ننقر على النقاط الثلاث بجوار مجموعة PokéAPI ونحدد Add Folder.

على غرار الآخرين، يطلب هذا اسمًا. المجلدات تشبه المجموعات داخل مجموعة، لذلك تحصل على خيارات مماثلة. دعنا نسمي هذا “Pokémon” وانقر على زر Save البرتقالي كما كان من قبل. الآن دعنا نضيف طلباتنا! أولاً، انقر على النقاط الثلاث بجوار مجلد Pokémon، على غرار كيفية إضافة مجلد إلى المجموعة، ولكن هذه المرة حدد Add Request.

دعنا نسمي هذا الطلب “Pokemon“. بينما قد يكون مربكًا أن لدينا طلب Pokemon داخل مجلد Pokémon، فإن Pokemon هو مجرد إحدى نقاط النهاية لمجموعة Pokémon. الآن، دعنا نستخدم نفس واجهة API بالضبط التي استخدمناها مع طلب Squirtle من قبل:

• نوع الطلب (Request Type): GET
• عنوان URL للطلب (Request URL): https://pokeapi.co/api/v2/pokemon/squirtle/

وعلى غرار ما سبق، عندما نضغط على زر Send الأزرق، يجب أن نرى طلبًا ناجحًا!

الآن دعنا نضيف طلبًا آخر. اتبع نفس العملية كما كان من قبل لإنشاء طلب جديد تحت مجلد PokéAPI Pokémon ودعنا نسمي هذا الطلب “Abilities“. إذا قمت بالتمرير عبر الاستجابة من نقطة نهاية Squirtle الأولى، فسترى الكثير من عناوين API URLs الأخرى. في الأعلى، لدينا abilities ولدينا اثنان مختلفان – “torrent” و “rain-dish“. اختر قدرة Squirtle المفضلة لديك وانسخ قيمة url في طلب Abilities الجديد الذي أنشأناه للتو، سأستخدم rain-dish. يمكننا ترك نوع الطلب كـ GET، والضغط على زر Send الأزرق، ويمكننا مرة أخرى رؤية استجابة ناجحة!

هنا نحصل على الكثير من المعلومات حول قدرة Squirtle “Rain Dish” وبعض التفاصيل تأتي بلغات مختلفة وهو أمر رائع! لذا لدينا الآن مجموعة PokéAPI جديدة مع مجلد Pokémon يمثل مجموعة نقاط نهاية API الخاصة بـ Pokémon بما في ذلك Pokemon و abilities. سنتوقف في الجزء 3 عند هذين الطلبين، ولكن لا تتردد في المتابعة وإضافة أكبر عدد ممكن من طلبات PokéAPI كما ترغب!

الجزء 4: إجراء طلبات POST لترجمة النصوص بأسلوب Yoda

حتى الآن، أجرينا فقط طلبات GET، ولكن ماذا لو أردنا إجراء طلب POST حيث نحتاج بالفعل إلى إرسال بعض البيانات؟ لإجراء طلب POST، سنستخدم واجهة Yoda Translator API من funtranslations.com. بينما تأخذ هذه الواجهة معاملًا واحدًا فقط، إلا أنها لا تزال نقطة نهاية عامة جيدة يمكننا استخدامها لفهم المفهوم.

أولاً، دعنا ننشئ مجموعة جديدة بطلب جديد:

• المجموعة (Collection): Fun Translations
• الطلب (Request): Yoda

هذه المرة، بدلاً من طلب GET، سيكون تكوين طلبنا كما يلي:

• نوع الطلب (Request Type): POST
• عنوان URL للطلب (Request URL): https://api.funtranslations.com/translate/yoda

الآن هذه المرة، إذا ضغطنا على زر Send الأزرق، سنلاحظ أننا لا نحصل على استجابة ناجحة 200، بل نحصل على 400!

لم نقم في الواقع بإعداد أي بيانات ليتم إرسالها إلى API وهي تتطلب تلك البيانات، لذا دعنا نضيفها. أسفل Request URL مباشرة، انقر على Body. ثم بدلاً من none، حدد raw كنوع الجسم (Body Type). أخيرًا، في أقصى يمين الأنواع، قم بتغيير Text إلى JSON.

ثم، في المساحة أسفل ذلك، يمكنك إضافة ما يلي:

{
  "text" : "Hello, I am learning how to test APIs with Postman!"
}

والآن انقر على زر Send الأزرق مرة أخرى ونحصل على استجابة ناجحة!

يمكننا تطبيق هذا المفهوم على أي واجهة API تقريبًا. لا يسمح لك Postman بنشر JSON فقط، بل يتيح لك استخدام التنسيقات الأخرى التي نراها مدرجة في قسم Body Type، مما يعني أن لديك الكثير من الخيارات اعتمادًا على ما تتطلبه واجهة API التي تستخدمها.

الجزء 5: مصادقة الطلبات باستخدام مفتاح API (مثال Lord of the Rings API)

لبقية هذا الدليل، سنستخدم واجهة Lord of the Rings API. أولاً، تتطلب واجهة Lord of the Rings API المصادقة لإجراء الطلبات باستخدام مفتاح API Key. لذا للبدء، ستحتاج قبل أن نتعمق، إلى إنشاء حساب مجاني.

• https://the-one-api.herokuapp.com/sign-up

بمجرد التسجيل وتسجيل الدخول، أول شيء ستراه هو مفتاح API الخاص بك! إما أن تنسخ هذا المفتاح أو تتذكر أين يمكنك العثور عليه لاحقًا. إذا غادرت الصفحة، يمكنك دائمًا الحصول عليه بالانتقال إلى Welcome ثم Account في قائمة التنقل بموقع API.

للبدء، دعنا ننشئ أولاً مجموعة وطلبًا جديدين:

• المجموعة (Collection): Lord of the Rings
• المجلد (Folder): Movie
• الطلب (Request): All Movies
• نوع الطلب (Request Type): GET
• عنوان URL للطلب (Request URL): https://the-one-api.herokuapp.com/v1/movie

بمجرد الانتهاء من الإعدادات المذكورة أعلاه، انقر على Send، وستلاحظ على الفور أنه يعطي استجابة تقول 401 وأنه غير مصادق عليه (unauthenticated). نظرًا لأن هذه الواجهة تتطلب مفتاح API Key، فهذا بالضبط ما توقعناه. لذا دعنا ننقر على علامة التبويب Authorization. يمكننا بعد ذلك تحديد نوع Bearer Token، وعلى اليمين، يمكننا لصق مفتاحنا الذي قمنا بإعداده للتو مع واجهة Lord of the Rings API.

وبمجرد الضغط على Send، نرى الآن استجابة ناجحة! لقد نجح هذا بشكل رائع، ولكن ماذا لو كان لدينا مجموعة من الطلبات التي تستخدم مفتاحًا واحدًا؟ هل يجب علينا إدارتها في كل طلب؟

بدلاً من إدارتها في كل طلب فردي، يمكننا إدارتها على مستوى المجموعة (Collection). دعنا أولاً نبني طلبًا آخر. تحت مجموعة Lord of the Rings وفي مجلد Movie، أنشئ طلبًا جديدًا:

• الطلب (Request): Quote by Movie ID
• نوع الطلب (Request Type): GET
• عنوان URL للطلب (Request URL): https://the-one-api.herokuapp.com/v1/movie/{id}

في هذا الطلب، دعنا نستخدم معرفًا (ID) من استجابة الطلب الأول، سأستخدم 5cd95395de30eff6ebccde5b وهو معرف فيلم The Two Towers، لذا سيبدو عنوان URL للطلب كما يلي:

https://the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b

الآن، بدلاً من تعيين رمز المصادقة (Token) في مصادقة الطلب (Request Authorization)، سنترك النوع كـ Inherit auth from parent. انقر على النقاط الثلاث بجوار المجموعة وحدد Edit.

هنا، سنقوم بنفس الشيء الذي فعلناه مع الطلب الأول ولكن على تكوين المجموعة (Collection configuration). حدد علامة التبويب Authorization، تحت النوع حدد Bearer Token، وفي حقل Token الصق رمز المصادقة الخاص بك مرة أخرى. أخيرًا، انقر على Update واضغط على زر Send الأزرق مرة أخرى ويمكننا رؤية طلب ناجح!

يمكننا الآن العودة إلى طلب All Movies وتحديث المصادقة (Authorization) لاستخدام نوع Inherit auth from parent ويجب أن يستمر في العمل!

ميزات إضافية وقدرات متقدمة في Postman

بينما غطيت الكثير من الأساسيات، هناك الكثير مما يمكنك فعله باستخدام Postman. إليك بعض من ميزاتي المفضلة:

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

إذا كنت تعمل كمطور في مشروع، فمن المحتمل أن يستخدم فريقك بيئات متعددة، مثل بيئة تطوير وبيئة إنتاج. بدلاً من إنشاء وصيانة طلبات منفصلة تمامًا، يمكنك إضافة متغير بيئة (Environment Variable) وتغيير هذا المتغير عند التبديل بين البيئات! تنطبق المتغيرات على العديد من السيناريوهات، ولكن هذا استخدام شائع. تحقق من وثائق Postman لمعرفة كيفية ذلك: https://learning.postman.com/docs/postman/variables-and-environments/variables/

استيراد وتصدير المجموعات والبيانات (Import and Export Collections and Data)

أحد الأشياء الرائعة في Postman هو أنه بمجرد تنظيم طلباتك بالكامل، يمكنك تصديرها ليستخدمها الآخرون. هذا يعني أيضًا أنه يمكنك استيراد المجموعات من أعضاء الفريق الآخرين. هذا يجعل من السهل جدًا التأكد من أن الجميع يستخدمون نفس المجموعة. مكافأة: يمكنك حتى تخزين هذه الملفات في مستودع Git repository، لأنها مجرد JSON. ولكن ضع في اعتبارك – إذا كنت تستخدم المصادقة (Authorization) على المجموعة كما تناولنا في هذا الدليل، فستحتاج إلى التأكد من عدم تضمينها عند تصدير مجموعتك: https://learning.postman.com/docs/postman/collections/importing-and-exporting-data/

الاختبار الآلي (Automated testing)

بمجرد أن يكون لديك مجموعة من الطلبات في مجموعة، والأفضل من ذلك، إذا كنت تخزنها في GitHub، يمكنك البدء في استخدام تلك الطلبات كجزء من طريقة لإدارة الاختبار الآلي لواجهة API الخاصة بك. بينما توجد بعض الحلول للقيام بذلك، يتضمن Postman أداة Collection runner مدمجة مباشرة في التطبيق و Newman هي أداة سطر أوامر تتيح لك تشغيل الاختبارات مباشرة من الطرفية (Terminal): https://www.postman.com/use-cases/api-testing-automation/

الخلاصة التقنية

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

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