ما هو API؟ شرح مبسط بأمثلة من الحياة اليومية

ما هو API بالضبط؟

واجهة API هي طريقة متفق عليها يطلب بها برنامج خدمة من برنامج آخر ويستلم منه ردًا. الاسم اختصار للعبارة الإنجليزية Application Programming Interface، وترجمتها العربية: واجهة برمجة التطبيقات.

كلمة «واجهة» هنا لا تعني شاشة تراها بعينك. المقصود نقطة اتصال بين برنامجين لها قواعد مكتوبة: ما الذي يمكن طلبه، وبأي صيغة يُكتب الطلب، وبأي صيغة يعود الرد.

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

تشبيه النادل: كيف تعمل واجهة API؟

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

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

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

كيف يبدو الطلب والرد؟

كل تعامل مع واجهة API رسالتان: طلب يرسله برنامجك، ورد يعود من الخادم. يذهب الطلب إلى عنوان محدد على الإنترنت، ويحمل ما تريده بالتفصيل.

افترض أن تطبيقًا يريد حالة الطقس في الإسكندرية. يرسل طلبًا يشبه GET /weather?city=Alexandria، ومعناه: أحضر لي طقس مدينة الإسكندرية. يعود الرد في أغلب الواجهات الحديثة بصيغة JSON، وهي طريقة لكتابة البيانات في أسماء وقيم:

{
  "city": "Alexandria",
  "temperature": 27,
  "condition": "sunny"
}

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

يحمل الرد أيضًا رمز حالة يخبر برنامجك بما حدث: هل نجح الطلب، أم كُتب بطريقة خاطئة، أم أن الخدمة متوقفة الآن. لذلك يفحص المبرمج الحالة قبل أن يستخدم البيانات.

أمثلة على API من حياتك اليومية في مصر

تستخدم واجهات API عشرات المرات كل يوم دون أن تراها. هذه مواقف مألوفة في مصر:

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

القاعدة واحدة في كل مثال: برنامج يحتاج شيئًا لا يملكه، فيطلبه من برنامج آخر بطريقة متفق عليها.

كلمات يقابلها المبتدئ في عالم API

تتكرر ست كلمات في أي شرح أو توثيق. افهم معناها مرة واحدة، وستقرأ بعدها أي صفحة توثيق بثقة أكبر.

الفرق بين API و SDK في جملتين

واجهة API هي قواعد الحديث مع الخدمة: العناوين وصيغة الطلب وصيغة الرد. حزمة SDK (اختصار Software Development Kit) مكتبة جاهزة يكتبها صاحب الخدمة لتتحدث بهذه القواعد نيابة عنك، فتكتب سطرًا واحدًا بدل تجهيز الطلب كله بيدك.

بلغة المطعم: الواجهة هي طريقة الطلب المتفق عليها، والحزمة صديق يحفظ القائمة ويطلب لك بالصيغة الصحيحة.

مفاتيح API أم نطاقات مسجلة؟

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

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

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

تعمل Gammal Tech بهذه الطريقة، فلا توجد فيها مفاتيح API. لكل مشروع رقم تعريف عام اسمه pid، وهو رقم وليس سرًا، ومعه قائمة بنطاقات المواقع المسجلة. يعمل الطلب من نطاق مسجل فقط، ويجب أن يستخدم النطاق اتصال HTTPS. هذه الطريقة مخصصة للمواقع، وليست حزمة لتطبيقات الهاتف.

كيف تجرب أول طلب API بنفسك؟

بداية سهلة للمبتدئ: صفحة HTML واحدة تستدعي خدمة جاهزة. المثال التالي يستخدم حزمة Gammal Tech للمواقع: يحمّل الحزمة، ثم يسجل الزائر دخوله، ثم يرسل سؤالًا إلى مساعد الذكاء الاصطناعي ويطبع الرد.

<script src="https://api.gammal.tech/sdk-web.js"></script>
<button id="try">جرّب</button>
<script>
document.getElementById('try').onclick = async function () {
  await GammalTech.login();
  const reply = await GammalTech.ai.ask('اشرح لي واجهة برمجة التطبيقات في سطرين', {
    system_prompt: 'أنت معلم يشرح البرمجة للمبتدئين في مصر بجمل قصيرة'
  });
  console.log(reply);
};
</script>

1. يحمّل السطر الأول الحزمة، فيظهر في الصفحة كائن واحد اسمه GammalTech تتفرع منه كل الخدمات.
2. تفتح الدالة GammalTech.login() نافذة تسجيل الدخول عند ضغط الزر، ويصل إلى صاحب الحساب رمز دخول لمرة واحدة. لا يخزن موقعك أي كلمة مرور.
3. ترسل الدالة GammalTech.ai.ask سؤالك، ومعه الخيار system_prompt الذي يحدد دور المساعد وأسلوبه.
4. يطبع السطر الأخير الرد في أدوات المطور داخل المتصفح، لتراه قبل أن تعرضه في الصفحة.

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

إذا استعنت بمساعد برمجة بالذكاء الاصطناعي، فأعطه دليل Gammal Tech. هو ملف نصي واحد كُتب بحيث يقرؤه المساعد ويعرف منه الدوال الموجودة وطريقة استخدامها.

مفاهيم خاطئة شائعة عن API

تختلط على المبتدئ أربعة أمور. تصحيحها مبكرًا يوفر عليك أسابيع من الحيرة:

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

في Gammal Tech مثلًا توجد لكل مشروع حصة شهرية بلا مقابل من استدعاءات الذكاء الاصطناعي للمستخدمين المسجلين ومن رموز الدخول، أما استدعاءات الزوار غير المسجلين فمدفوعة دائمًا. كل طلب يُحسب استدعاءً واحدًا، والأرقام الحالية في دليل Gammal Tech.

أسئلة شائعة عن API