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

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

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

ما هو API بكلمات بسيطة؟

الـ API (اختصار Application Programming Interface، أي واجهة برمجة التطبيقات) هو مجموعة قواعد متفق عليها تسمح لبرنامج بأن يطلب بيانات أو خدمة من برنامج آخر، دون أن يعرف كيف يعمل ذلك البرنامج من الداخل.

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

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

كيف يعمل الـ API خطوة بخطوة؟

كل تعامل مع واجهة ويب هو طلب (Request) يرسله برنامج، ورد (Response) يعود من الخادم. يتكون الطلب من عنوان وطريقة وبيانات إضافية، ويتكون الرد من رمز حالة وبيانات.

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

أمثلة على الـ API من حياتك اليومية

أنت تستخدم واجهات برمجية كثيرًا كل يوم دون أن تلاحظ. وأسهل طريقة لاستيعاب ما هو API هي أن تتعرف عليه في تطبيقات تعرفها بالفعل:

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

ما معنى REST وJSON وطرق HTTP؟

الـ REST أسلوب شائع لتصميم واجهات الويب، يعامل البيانات كموارد لكل منها عنوان، ويستخدم طرق بروتوكول HTTP لتحديد العملية. أما JSON فصيغة نصية خفيفة لتبادل البيانات، يسهل على البشر قراءتها وعلى البرامج تحليلها.

مثال على رد بصيغة JSON يصف مهمة: {"id": 1, "title": "Buy milk", "completed": false}. القيم بين علامات التنصيص نصوص، والأرقام بلا علامات، وtrue وfalse قيم منطقية.

وكثيرًا ما تضيف إلى العنوان معاملات استعلام (Query Parameters) بعد علامة الاستفهام لتحديد ما تريده بدقة، مثل رقم الصفحة وعدد النتائج: /products?page=2&limit=10. هذا الطلب يقول للخادم: أعطني الصفحة الثانية من المنتجات، بعشرة منتجات في كل صفحة، بدل أن يرسل لك آلاف المنتجات دفعة واحدة.

ورموز الحالة الأكثر شيوعًا: 200 نجاح، و201 تم الإنشاء، و400 طلب غير صحيح، و401 غير مصرح لك، و404 المورد غير موجود، و500 خطأ في الخادم. يمكنك الرجوع إلى توثيق HTTP في MDN لشرح كل رمز وطريقة بالتفصيل.

ما مفتاح الـ API ولماذا يجب أن يبقى سرًا؟

مفتاح الـ API (API Key) رمز سري تعطيك إياه الخدمة لتعرف من يرسل الطلبات وتحاسبه وتحدد صلاحياته. من يحصل على مفتاحك يستطيع استخدام الخدمة باسمك، وقد يستهلك رصيدك أو يصل إلى بياناتك.

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

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

ما الفرق بين الـ API والـ Webhook؟

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

مثال عملي من ربط الدفع على موقع Apex: بعد أن يدفع العميل في صفحة الدفع المستضافة لدى البوابة، ترسل البوابة Webhook إلى خادمنا يؤكد نجاح العملية. ولأن أي جهة قد تحاول إرسال إشعار مزيف، فالإشعار موقّع، ونتحقق من توقيعه باستخدام HMAC قبل أن نعتمد الدفع. الـ HMAC طريقة لحساب توقيع من محتوى الرسالة ومفتاح سري مشترك، فإن تغيّر حرف واحد في الرسالة لم يعد التوقيع مطابقًا.

تفاصيل ربط بوابات الدفع من منظور صاحب المشروع تجدها في مقال ربط بوابة الدفع بموقعك في مصر.

كيف تقرأ توثيق أي API قبل أن تستخدمه؟

كل خدمة جادة تنشر توثيقًا (Documentation) لواجهتها، وهو المرجع الوحيد الموثوق لطريقة استخدامها. وبعد أن تفهم ما هو API نظريًا، تصبح قراءة التوثيق هي المهارة العملية الأهم، لأن كل خدمة تختلف في تفاصيلها.

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

1. العنوان الأساسي (Base URL): الجزء الثابت الذي تبدأ به كل الطلبات.
2. طريقة المصادقة: هل تحتاج مفتاحًا في الترويسات؟ أم تسجيل دخول بطريقة OAuth؟
3. قائمة العناوين (Endpoints): ما الموارد المتاحة، والطريقة المطلوبة لكل منها، والمعاملات الإلزامية والاختيارية.
4. أمثلة الطلب والرد: أغلب التوثيقات تعرض طلبًا جاهزًا وشكل الرد المتوقع. ابدأ دائمًا بنسخ المثال كما هو وتشغيله.
5. حدود الاستخدام (Rate Limits): عدد الطلبات المسموح بها في فترة زمنية، وما يحدث عند تجاوزه.
6. رموز الأخطاء: ماذا يعني كل خطأ خاص بالخدمة وكيف تتعامل معه.
7. الإصدار (Version): كثير من الواجهات تضع رقم الإصدار في العنوان، وقد توقف الإصدارات القديمة بعد فترة.

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

جرّب أول API بنفسك في دقيقتين

أسهل تجربة هي إرسال طلب GET إلى خدمة JSONPlaceholder، وهي واجهة عامة مجانية مخصصة للتدريب تعيد بيانات وهمية.

1. افتح أي صفحة في متصفحك واضغط F12، ثم انتقل إلى تبويب Console.
2. اكتب هذا السطر واضغط Enter: fetch("https://jsonplaceholder.typicode.com/todos/1").then(r => r.json()).then(data => console.log(data));
3. ستظهر لك بيانات مهمة بصيغة JSON فيها رقم وعنوان وحالة إنجاز.
4. غيّر الرقم 1 في نهاية الرابط إلى 2 أو 3 ولاحظ تغير البيانات.

ويمكنك تنفيذ الطلب نفسه من سطر الأوامر بالأمر curl https://jsonplaceholder.typicode.com/todos/1. وإذا أردت فهم fetch وasync/await بعمق، فراجع تعلم JavaScript للمبتدئين.

الخلاصة

• الـ API طريقة متفق عليها لكي يطلب برنامج بيانات أو خدمة من برنامج آخر دون معرفة تفاصيله.
• كل تعامل هو طلب (عنوان وطريقة وترويسات وبيانات) ورد (رمز حالة وبيانات بصيغة JSON غالبًا).
• مفاتيح الـ API أسرار: لا تضعها في كود الواجهة ولا ترفعها إلى GitHub.
• في الـ API أنت تسأل، وفي الـ Webhook يأتيك الإشعار تلقائيًا، ويجب التحقق من توقيعه.
• ابدأ التجربة بخدمة تدريبية عامة مثل JSONPlaceholder قبل الربط بخدمات حقيقية.