ما هو API؟ — دليل مصوّر

يشير اختصار API إلى واجهة برمجة التطبيقات (Application Programming Interface). وهي طريقة يتواصل بها برنامجان مع بعضهما عبر الإنترنت.

تشبيه المطعم

تخيّل مطعمًا:

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

نموذج العميل والخادم

┌─────────┐    Request (HTTP)    ┌─────────┐
│  Client  │ ──────────────────> │  Server │
│ (mobile) │                     │ (Flask) │
│          │ <────────────────── │         │
└─────────┘    Response (JSON)   └─────────┘

• العميل: تطبيق الجوال الخاص بك المبني بـ React Native (أو المتصفح، أو خادم آخر)
• الخادم: الواجهة الخلفية المكتوبة بـ Flask، وهي التي تعالج الطلبات وتتواصل مع قاعدة البيانات

طرق HTTP

حين يتواصل تطبيقك مع خادم، فإنه يستخدم طرق HTTP ليصف ما يريد فعله:

دورة الطلب والاستجابة

حين يرسل تطبيق الجوال رسالة:

1. يكتب المستخدم "Hello!" ويضغط على إرسال
2. يرسل تطبيق الجوال طلب POST إلى http://server:5000/chat
   مع جسم الطلب: {"message": "Hello!"}
3. تستقبل الواجهة الخلفية Flask الطلب
4. تحفظ الواجهة الخلفية الرسالة في قاعدة بيانات SQLite
5. تستدعي الواجهة الخلفية OpenAI API للحصول على رد
6. تحفظ الواجهة الخلفية رد الذكاء الاصطناعي في قاعدة البيانات
7. تعيد الواجهة الخلفية JSON: {"reply": "Hi there! How can I help?"}
8. يستقبل تطبيق الجوال الاستجابة ويعرضها

ما هو JSON؟

JSON (JavaScript Object Notation) هي صيغة تُنسَّق بها البيانات عند إرسالها بين العميل والخادم.

{
    "id": 1,
    "message": "Hello!",
    "sender": "user",
    "timestamp": "2025-01-15T10:30:00Z"
}

إنه يشبه قاموس Python أو كائن JavaScript، ويمكن لكلتا اللغتين التحويل من JSON وإليه بسهولة.

ما هي نقطة النهاية (endpoint)؟

نقطة النهاية هي مزيج محدد من عنوان URL وطريقة HTTP:

رموز الحالة

تتضمن كل استجابة رمز حالة يخبرك إن نجح الطلب أم لا:

ملخص بصري

┌──────────┐         ┌──────────┐         ┌──────────┐
│  Mobile   │  POST   │  Flask   │  POST   │  OpenAI  │
│   App    │ ──────> │  Server  │ ──────> │   API    │
│          │         │          │         │          │
│  Send    │  JSON   │  Save to │  JSON   │ Generate │
│ "Hello!" │         │  SQLite  │         │  reply   │
│          │ <────── │          │ <────── │          │
│          │  JSON   │          │  JSON   │          │
│ Display  │  reply  │  Send    │  reply  │          │
│  reply   │         │  back    │         │          │
└──────────┘         └──────────┘         └──────────┘

الخلاصة

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