الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح

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

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

هذا المقال هو جزء من سلسلة مقالات حول الواجهة البرمجية API وكيفية الاستفادة منها في بناء تطبيق ويب:

1. مدخل إلى الواجهات البرمجية API
2. الاتصال بواجهة زد البرمجية وفهم عملية الاستيثاق والتصريح
3. أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API
4. تطوير تطبيق عملي يزيد من احتفاظ العملاء عبر واجهة زد البرمجية

آلية التواصل وتنظيم عملية الاتصال

قبل أن أكمل الحديث عن الواجهة البرمجية، هل سألت نفسك، لماذا ﻻ يذهب الزبائن مباشرةً إلى الطباخ في مقال المطعم السابق ويخبروه بما يريدون تناوله من مختلف الأطباق التي تُقدَّم في المطعم؟

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

في حالة أخرى، هل يستطيع أي عامل في المطعم أن يكون نادﻻ؟ في هذه الحالة ستكون فوضى أخرى ولكن بدرجة أقل، بحيث هنالك احتمالية كبيرة ﻷن تُحضّر نفس الطلبية أكثر من مرة لنفس الشخص وفي مرات أخرى من الممكن نسيان طلبية زبون آخر، وفي حالة أخرى، لن يكون باﻹمكان معرفة صاحب الطلبية من غيره أو حتى عدم فهم طلبية الزبون.

كانت هذه الحالة الخاصة بالمطعم، فلك أن تتخيل كقاميف ستكون في حالة الواجهات البرمجية؟ تقريبا هي نفس الشيء ولكنها بشكل أسوأ بكثير بسبب أن الواجهة البرمجية API تنظِّم الكثير والكثير من الطلبات لعدد كبير جدا من العملاء التي قد تصل إلى أرقام كبيرة وخيالية.

حُلت المشكلة في حالة المطعم بتحديد من يستطيع التحدث مع الزبائن وتدريبهم بأخذ الطلبيات إلى الطباخ وفريقه ومن ثم إعادة الاستجابة أو الناتج الذي حُضِّر إلى الزبون نفسه الذي طلبها تحديدًا ولم يسبق أن دخلت مطعمًا ونسي النادل طلبيتي أو جاءني بطلبية أخرى فهل سألت نفسك عن السبب؟ هل رأيته يكتب في ورقة أمامه ويسألك عن اسمك وينظر في الطاولة والموقع برهة ويذهب؟ وهل قلت لنفسك إن تأخر لقد نسيني أو لم يعرفني ثم يعود جالبًا لك طلبيتك التي طلبتها تمامًا دون أي نسيان؟ للنادل آلية يتذكر فيها صاحب كل طلبية وطلبيته بالضبط ولا ينساها مطلقًا والأمر في حالة الواجهة البرمجة مشابه تمامًا.

حلت المشكلة السابقة عن طريق ما يسمى المفتاح المساعد Token وهو سلسلة نصية String تخص العميل طالب الخدمة وتميزه تصدرها الواجهة البرمجة غالبًا (سواءً بمقابل مادي أو مجرد التسجيل في منصة مقدم الواجهة البرمجية) بحيث يرسل المفتاح المساعد Token مع كل طلب خدمة إلى الواجهة البرمجية، من ثم تتحقق الواجهة البرمجية من صلاحية المفتاح المساعد، إن كان صالحا، فستُقدَّم الخدمة المطلوبة للعميل، أما إن لم يكن صالحا، فعادةً ما تُرجع رسالة خطأ تفيد بأن المفتاح المساعد غير صالح، أي لا يمكن إلا لأشخاص مخوليين التواصل مع الواجهة البرمجية وإلا لعمت الفوضى وجاء الجميع للاستفادة من الخدمة التي تقدمها الواجهة.

التواصل مع واجهة منصة زد البرمجية

حتى نفهم أكثر هذه العملية، سنأخذ مثالًا من الحياة العملية، بحيث سنوجه طلبات إلى الواجهة البرمجية لمنصة زد من أجل اﻹستعلام عن بعض الخدمات الخاصة بهم، دعونا نبدأ.

قبل أن نبدأ، ستحتاج إلى التالي:

1. حساب مطور على منصة زد
2. برناج إرسال طلبات HTTP مثل Insomnia أو البرنامج الأكثر شهرة Postman (أصبح البرنامج بطيئًا نوعا ما موازنةً ببرنامج Insomnia ولهذا سنستخدم اﻷخير).

إنشاء حساب مطور على منصة زد

ندخل إلى بوابة المطورين في منصة زد، سنجدها بسيطة وسهلة اﻹستخدام، يكفي فقط أن عنوان بريدك اﻹلكتروني في الخانة المخصصة، كما في الصورة التالية:

بعد أن تدخل عنوان بريدك اﻹلكتروني، والضغط على الزر START NOW، سيُعاد توجيهك إلى لوحة تحكم المطورين، أين يمكنك أخذ نظرة عن الواجهة البرمجية لمنصة زد

عند الضغط على ZidAPI ﻻكتشاف تفاصيل الواجهة البرمجية لمنصة زد، كما في الصورة الموالية:

ستظهر لنا النافذة التالية:

وفيها نجد جميع المعلومات اللازمة للاتصال بالواجهة البرمجية لمنصة زد، بحيث ذُكرت جميع نقاط الوصول Endpoints، مع المعلومات التي يجب إرسالها والمعلومات التي ستُحصّل عند كل نقطة وصول.

في الجزء Gateway Environments، وعند الضغط على القائمة Production and Sandbox، ستظهر معلومات مهمة، هي نقطة الوصول الرئيسية للواجهة البرمجية، ولكن ما الذي تعنيه Production and Sandbox.

ببساطة Production Environment، هي البيئة الإنتاجية للواجهة البرمجية التي عليك استخدامها في مشروعك النهائي المقدم كخدمة للزبائن، بحيث أن كل العمليات التي تحدث فيها، هي عمليات فعلية. أما Sandbox Environment، فهي البيئة التطويرية التجريبية التي تستخدم أثناء عملية التطوير، بحيث أن جميع العمليات التي تتم فيها، هي عمليات تجريبية فقط.

في الواجهة البرمجية لمنصة زد، نلاحظ أن اﻹختلاف بين البيئة الإنتاجية والبيئة التطويرية التجريبية طفيف، فهو يمكن فقط في البروتوكول المستخدم HTTP.

فهم طلبيات HTTP وأنواعها

نريد اﻵن ااتصال بالواجهة البرمجية لمنصة زد، كل المعلومات لدينا ولم يبقى إﻻ عملية اﻹتصال. للقيام بذلك، نحتاج برنامجا ﻹرسال طلبات HTTP، أو ما يسمى باللغة اﻹنجليزية HTTP Client، ولكن ما هو هذا البرنامج، وما هو عمله؟

ببساطة، برنامج HTTP Client، هو وسيط بينك وبين الواجهة البرمجية، بحيث يرسل الطلبات حسب بروتوكول HTTP. هنالك عدة أنواع من الطلبات الخاصة ببروتوكول HTTP، أشهرها GET و POST و PUT و DELETE.

كمعلومة جانبية، متصفح اﻹنترنت الذي تعرفه، مثل كروم Google Chrome، وفايرفوكس أو أي متصفح آخر يعتبر HTTP Client، أي لديه القدرة أن يرسل طلبات HTTP للاستزادة في هذه النقطة، سأشرح أنواع طلبيات HTTP وهي:

• الطلب GET: يستخدم لجلب بيانات من الخادم أو الواجهة البرمجية.
• الطلب POST: يستخدم ﻹرسال البيانات إلى الخادم أو الواجهة البرمجية.
• الطلب PUT: يستخدم لتحديث بيانات في الخادم.
• الطلب DELETE: يستخدم لحذف البيانات على الخادم.

استعمال Insomnia لإدارة الطلبيات التجريبية

سنستخدم برنامج Insomnia من أجل إرسال الطلبات لواجهة زد البرمجية، يمكنك تنزيل البرنامج من الموقع الرسمي للشركة المطورة.

بعد التحميل والتثبيت، ستظهر نافذة البرنامج كما في الصورة:

واجهة بسيطة وسهلة اﻹستخدام، أليس كذلك؟ نضغط على الزر New Request ﻹرسال طلب للواجهة البرمجية لمنصة زد:

1. لتسمية الطلب الجديد، يمكنك اختيار أي اسم كان، أو ترك الاسم الافتراضي، ولكن يفضل أن تُسمى الطلبات بأسماء ذات معنى للعمل الذي تنجزه.
2. نوع الطلب، ويمكننا تحديد أي طلب كان حسب حاجتنا وحسب ما تفرضه الواجهة البرمجية.
3. إنشاء وحفظ الطلب الجديد.

احفظ الطلب الجديد باسم Get Profiles، لأننا سنتصل بالواجهة البرمجية لمنصة زد من أجل جلب الملفات الشخصية Profiles المتعلقة بحسابنا على منصة زد.

التعرف على نقاط الوصول

حينما نتصفح صفحة Developer Portal التي وفرتها منصة زد، سنجد توثيقا يخص الواجهة البرمجية لمنصة زد. التوثيق هو شرح لجميع نقاط الوصول Endpoints للواجهة البرمجية، وما هي المعلومات التي عليك إرسالها لكل نقطة وصول والمعلومات التي ستتحصل عليها من نقطة الوصول تلك.

تلاحظ أن هناك نقطة وصول تتيح لنا الحصول على الملفات الشخصية Profiles، وهي موجودة على المسار Path:

/managers/account/profile

تذكر أن علينا إضافة نقطة الوصول الرئيسية للواجهة البرمجية قبل رابط تلك المسارات أو نقاط الوصول الفرعية، وبالتالي يصبح الرابط النهائي الذي علينا توجيه الطلب إليه كالتالي:

http://api.zid.dev/app/v1/managers/account/profile

ولكن كيف كونا الرابط النهائي لنقطة الوصول هذه؟

اﻷمر بسيط جدا، من التوثيق الخاص بالواجهة البرمجية لمنصة زد، فنجد Servers والتي تحوي الرابط الرئيسي لكل من البيئة الإنتاجية والبيئة التجريبية للواجهة البرمجية.

طلب التصريح والاستيثاق من الطلبية

بعدها نجد مسار نقطة الوصول Endpoint تمامًا مثل هذا المثال:

لكل نقطة وصول معلومات مطلوبة حتى تستطيع الوصول إليها واستخدامها، فمثلا نقطة الوصول الموضح بالصورة تتطلب مُعامِلات Parameters خاصة بها وهي:

• X-MANAGER-TOKEN: وهو المفتاح المتجر المساعد الذي يخص المتجر اﻹلكتروني المراد تطبيق العملية عليه ولكل متجر في زد مفتاح مساعد خاص به فقط.
• Accept-Language: وهي اللغة التي تريد أن ترسل لك الواجهة البرمجية الإجابة Response فيها، وتأخذ القيمة ar للغة العربية أو en للغة اﻹنجليزية.

الآن، سنرسل الطلب للواجهة البرمجية لمنصة زد، وننتظر الرد:

لقد واجهتنا رسالة تفيد بأن علينا إرفاق مفتاح المبرمج المساعد Token مع الطلب حتى يتم التحقق بأننا مخولون للدخول واستعمال نقاط الوصول الخاصة بالواجهة البرمجية، هو نفسه الذي شرحناه آنفًا في بداية المقال فكما ذكرنا أنه يجب أن يكون مصرحًا لك استعمال الواجهة البرمجية وإلا جاء أي أحد واستعملها وستتأكد الواجهة البرمجة من ذلك التصريح وتستوثق منه.

تذكر أن العملية مشابهة تمامًا للباب ومفتاحه فلأي مكان باب مثل منزلك عليه باب ولا يخول لأي أحد دخوله إلا من يملك مفتاح الباب، وتخيل أن يكون باب المنزل دون مفتاح أو أن يملك أي أحد مفتاح باب منزلك! العملية هنا نفسها تمامًا.

الحصول على مفاتيح التصريح المخولة

التوثيق الخاص بالواجهة البرمجية لمنصة زد، يشرح طريقة الحصول على المفتاح المبرمج المساعد أي المفتاح الخاص بك الذي يصرح لك استعمال الواجهة البرمجية، يكفيك أن تتوجه إلى التبويب Subscriptions ومنه أنشئ التطبيق الخاص بك، باستخدام Subscriptions & Key Generation Wizard.

سيطلب منك معلومات بسيطة تعريفية بالتطبيق، تابع الصور التالية:

عليك الآن أن تنتظر إلى حين الموافقة على التطبيق من طرف فريق منصة زد.

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

هنالك طريقتان: الأولى، عن طريق لوحة التحكم في منصة زد نفسها، بحيث من نفس الصفحة السابقة، نختار التطبيق الذي أنشاناه، ونختار Manage App، وبعدها نختار Sandbox Keys، حتى نستعمل الواجهة البرمجية الخاصة بالتجربة فقط:

نضغط على Generate Access Token، لتظهر نافذة منبثقة، تطلب تأكيد توليد المفتاح المساعد Token:

بعد الضغط على GENERATE، ستظهر سلسلة نصية متكونة من أحرف وأرقام، علينا نسخها ولصقها في مكان يسهل علينا الرجوع إليه.

الطريقة الثانية ﻹنشاء مفتاح مساعد هي أن نتجه إلى التبويب Subscriptions في قسم Zid Developer Portal، ونختار التطبيق الذي أنشأناه سابقًا:

نضغط على Sandbox Keys:

ثم نضغط بعدها على CURL TO GENERATE ACCESS TOKEN:

نختار الرابط الثاني (الطريقة الثانية) ﻹنشاء المفتاح المساعد Access Token ونلضغط على الزر الموجود على الجانب من أجل نسخه، ونفتح برنامج Insomnia:

بعدها نختار كما موضح في الصورة:

ستظهر نافذة تسألك إن كنت تريد استيراد السطر في نفس النافذة أم نافذة جديدة، اختر ما يناسبك سيُنشَأ طلب جديد من نوع POST مثل الصورة الموالية:

اﻵن علينا أن نضيف ترويسة إلى قبل إرسال طلبنا عن طريق الذهاب إلى التبويب Header وإضافته كالتالي:

ما الذي يعنيه هذا الجزء من الطلب؟

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

إن لم تستوعب الفكرة اﻵن فلا داعي للقلق، سنشرح كل شيء بالتفصيل في المقاﻻت القادمة ويكفي اﻵن أن تضغط على Send، ﻹرسال طلب إنشاء مفتاح مساعد جديد، وسيُرسَل إليك كالتالي:

بقيت اﻵن خطوة أخيرة وهي إنشاء متجر تجريبي على منصة زد من أجل التجربة عليه، المنصة تمنحك فترة 14 يوما من أجل اكتشاف خصائص المنصة والتعرف على طريقة التعامل معها (انظر مقال كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد لمزيد من التفاصيل حول كيفية إنشاء متجر).

بعد أن تنشئ متجرًا على منصة زد، أدخُل إلى حسابك وتوجه إلى صفحة "اﻹعدادات"، ثم اختر "الربط مع الخدمات"، ثم اضغط على زر "قم بإنشاء رمز المصادقة Manager Token":

إنشاء أول اتصال مع الواجهة البرمجية

اﻵن وبعد أن توافرت لدينا كل المفاتيح والمعلومات المطلوبة للاتصال بالواجهة البرمجية، يمكننا العودة للطلب الذي أنشأناه سابقا واﻹتصال بالواجهة البرمجية لمنصة زد كالتالي:

ﻻحظ أننا ضمنا كلًا من مفتاح المبرمج Access Token ومفتاح المتجر Manager Token في ترويسة Header الطلب تحت تسمية Authorization و X-MANAGER-TOKEN على الترتيب، وهو ما يسمح للواجهة البرمجية لمنصة زد من التحقق من قدرتنا على الوصول إلى نقطة الوصول Endpoint هته وهل نمتلك الصلاحية لذلك وتعرف أيضًا أي متجر بالتحديد نريد تطبيق العمليات عليه.

إن كنت قد تساءلت لماذا أضفنا كلمة Bearer قبل السلسلة النصية في Authorization، فببساطة هنالك عدة أنواع من المفاتيح المساعدة ولكن أشهرها هي Basic وBearer، اﻹختلاف بينهما هو في نمط التشفير وفك التشفير فقط.

خاتمة

تعلمنا في هذا المقال كيفية إنشاء أول اتصال مع واجهة برمجية نموذجية -مثل واجهة منصة زد- بتأمين مفاتيح التصريح المطلوبة وكل المعلومات اللازمة لها وأصبح بإمكانك الآن تطبيق ما تعلمته في المقال على أي واجهة برمجية والاتصال بها والاستفادة من الخدمات التي تقدمها على الوجهة التي تريد.

سنتعرف في المقال التالي أكثر على واجهة منصة زد والاتصال بمختلف نقاط وصول الواجهة البرمجية والاطلاع على المعلومات التي يمكن أن تزودنا فيها وكيف يمكن الاستفادة منها.

اقرأ أيضًا

• المقال التالي: أمثلة عملية لاستخدام واجهة برمجة متاجر زد zid API
• التعرف على لوحة تحكم متجر زد الإلكتروني وضبط عمليات المتجر
• كيفية إنشاء متجر إلكتروني متكامل باستعمال منصة زد
• الواجهة البرمجية Fetch API في جافاسكريبت