ما هو API؟ دليل مبسّط لمنشئي التطبيقات
الـ API (واجهة برمجة التطبيقات) طريقة محددة يطلب بها برنامج من برنامج آخر بيانات أو يطلب منه تنفيذ شيء ما. يرسل تطبيقك طلبًا بصيغة متفق عليها — "أعطني حجوزات الغد"، "اخصم 20 يورو من هذه البطاقة"، "لخّص هذا النص" — فيعيد النظام الآخر ردًا منظمًا. وبهذه الطريقة تتواصل أجزاء التطبيق مع بعضها، ويستخدم تطبيقك الخدمات الخارجية مثل المدفوعات والبريد والخرائط والذكاء الاصطناعي.
لماذا تهم الـ APIs عند البناء بالذكاء الاصطناعي
تقريبًا كل تطبيق مفيد يتكون من أجزاء تتواصل عبر الـ APIs:
- داخل تطبيقك، تستدعي الشاشات في المتصفح واجهة API الخاصة بالخادم الخلفي لتحميل البيانات وحفظها.
- خارج تطبيقك، يستدعي الخادم الخلفي واجهات API لشركات أخرى: Stripe لقبول المدفوعات، ومزود بريد لإرسال الإيصالات، ومزود نماذج الذكاء الاصطناعي لتوليد النصوص.
وعندما تطلب من منشئ التطبيقات بالذكاء الاصطناعي أن "يقبل المدفوعات" أو "يضيف ملخصًا بالذكاء الاصطناعي"، فإنه في الحقيقة يكتب كودًا يستدعي API. ومعرفة الأساسيات تساعدك على فهم ما يحتاجه الذكاء الاصطناعي منك (عادةً حساب لدى تلك الخدمة ومفتاح API)، وأين يمكن أن تسوء الأمور، وكم ستكلّف.
تشبيه من الحياة اليومية
فكّر في مطعم. لا تدخل المطبخ وتطبخ بنفسك. تقرأ قائمة الطعام، وتخبر النادل بما تريد بطريقة يفهمها المطبخ، فيعود النادل بطعامك — أو يخبرك بأن الطبق نفد.
- قائمة الطعام هي وثائق الـ API: قائمة بما يمكنك طلبه وكيفية طلبه.
- النادل هو الـ API: الطريقة الواحدة المتفق عليها التي تدخل بها الطلبات وتخرج بها الردود.
- المطبخ هو النظام الآخر: لا تحتاج إلى معرفة ما يجري داخله.
- طلبك هو الطلب؛ الطبق هو الرد.
يستطيع المطبخ تغيير أفرانه وطاقمه دون أن يؤثر ذلك عليك، ما دامت القائمة كما هي. وهذه هي القيمة الحقيقية للـ API: تتيح لنظامين العمل معًا دون أن يحتاج أي منهما إلى معرفة كيفية بناء الآخر.
كيف يعمل طلب API على الويب
أغلب الـ APIs التي ستصادفها هي واجهات ويب تعمل عبر HTTP، وهو البروتوكول نفسه الذي يستخدمه متصفحك. ولكل طلب بعض الأجزاء:
| الجزء | ما هو | مثال |
|---|---|---|
| الطريقة (Method) | نوع الإجراء | GET (قراءة)، POST (إنشاء) |
| عنوان URL / نقطة النهاية (Endpoint) | عنوان الشيء الذي تتعامل معه | https://api.example.com/bookings |
| الترويسات (Headers) | معلومات إضافية، منها هويتك | Authorization: Bearer <your key> |
| الجسم (Body) | البيانات التي ترسلها، للإنشاء والتحديث | {"name": "Lena", "time": "14:00"} |
ولكل رد أيضًا:
| الجزء | ما هو | مثال |
|---|---|---|
| رمز الحالة (Status code) | رقم يوضح كيف سار الطلب | 200 تم، و201 تم الإنشاء، و404 غير موجود |
| الجسم (Body) | البيانات المعادة، عادةً بصيغة JSON | {"id": 5001, "status": "confirmed"} |
JSON (JavaScript Object Notation) صيغة نصية بسيطة من أسماء وقيم داخل أقواس معقوفة. وهي الطريقة القياسية لتبادل البيانات في واجهات الويب.
REST: النمط الأكثر شيوعًا
REST عرف واسع الانتشار لتصميم واجهات الويب. يحصل كل نوع من الأشياء على عنوان URL خاص به، وتحدد الطرق القياسية ما الذي تفعله به. وهكذا قد تبدو واجهة REST لتطبيق حجوزات:
| الطريقة | نقطة النهاية | ماذا تفعل |
|---|---|---|
GET | /api/bookings | عرض الحجوزات |
GET | /api/bookings/5001 | عرض حجز واحد |
POST | /api/bookings | إنشاء حجز جديد |
PATCH | /api/bookings/5001 | تغيير جزء من الحجز، مثل وقته |
DELETE | /api/bookings/5001 | إلغاء (حذف) حجز |
كما توجد طريقة PUT، وهي تقليديًا تستبدل السجل كاملًا، بينما PATCH يغيّر الحقول التي ترسلها فقط.
رموز الحالة التي سترها أكثر من غيرها:
| الرمز | المعنى |
|---|---|
200 / 201 | نجاح / تم الإنشاء |
400 | طلب خاطئ — شيء في ما أرسلته خاطئ أو ناقص |
401 | غير مصادَق — لا يوجد تسجيل دخول أو مفتاح صالح |
403 | ممنوع — أنت معروف لكنك غير مسموح لك بهذا |
404 | غير موجود |
429 | طلبات كثيرة جدًا — تجاوزت حد المعدل (rate limit) |
500 | حدث خطأ على الخادم |
عندما ينكسر تطبيقك، غالبًا ما يكون رمز الحالة أسرع دليل. فالرمز 401 من مزود دفع يعني عادةً أن مفتاح API مفقود أو خاطئ؛ والرمز 429 يعني أنك تستدعي الخدمة بكثرة.
REST ليس النمط الوحيد — فهناك GraphQL وواجهات بأسلوب RPC أيضًا — لكن REST هو ما تستخدمه معظم الخدمات والخوادم الخلفية المبنية بالذكاء الاصطناعي.
مثال تطبيقي: تأكيد حجز
عندما يحجز عميل قصة شعر في تطبيق صالون، قد تحدث عدة استدعاءات API خلال ثانية أو ثانيتين:
- صفحة الحجز في المتصفح ترسل
POST /api/bookingsمع الخدمة والوقت وبيانات العميل إلى خادمك الخلفي. - يتحقق خادمك من أن الفترة متاحة، ويحفظ الحجز في قاعدة البيانات، ويعيد
201 Created. - يستدعي خادمك واجهة API لمزود البريد باستخدام مفتاحه السري: "أرسل هذا التأكيد إلى lena@example.com."
- إذا كان هناك عربون، يطلب خادمك من واجهة API لمزود الدفع إنشاء جلسة دفع ويرسل العميل إليها.
- لاحقًا، يستدعي مزود الدفع تطبيقك أنت ليخبره بنجاح الدفعة. وهذا الاستدعاء العكسي هو Webhook.
الخطوتان الأولى والثانية هما واجهة API الخاصة بك بين الواجهة الأمامية والخلفية. أما الخطوات من 3 إلى 5 فهي واجهات API لأطراف ثالثة.
مصطلحات شائعة مشروحة
| المصطلح | معناه |
|---|---|
| Endpoint (نقطة النهاية) | عنوان URL محدد تستجيب له واجهة API. |
| API key (مفتاح API) | سلسلة سرية تعرّف تطبيقك للخدمة. تعامل معها كما تتعامل مع كلمة المرور. |
| Authentication (المصادقة) | إثبات هوية المتصل — بمفتاح أو رمز أو تسجيل دخول. انظر ما هي المصادقة. |
| Rate limit (حد المعدل) | سقف لعدد الطلبات التي يمكنك إرسالها في فترة زمنية. |
| SDK (حزمة تطوير البرمجيات) | مكتبة كود جاهزة تُسهّل استدعاء واجهة API معينة. |
| Documentation (الوثائق) | "القائمة": ما نقاط النهاية الموجودة، وما الذي تقبله وتعيده. |
| Sandbox / Test mode (بيئة الاختبار) | نسخة من الخدمة للاختبار دون أموال حقيقية أو بيانات حقيقية. |
| Webhook | استدعاء من خدمة أخرى إلى تطبيقك عندما يقع حدث ما. |
أخطاء شائعة ومفاهيم خاطئة
- وضع المفاتيح السرية في الواجهة الأمامية. أي شيء في كود يعمل داخل المتصفح يمكن لأي زائر أن يراه. يجب أن تبقى المفاتيح السرية على الخادم، في متغيرات البيئة أو الأسرار.
- لصق المفاتيح في المحادثة. قد يُحفظ سجل المحادثة. استخدم ميزة الأسرار لدى منشئ التطبيق بدلًا من ذلك، وغيّر أي مفتاح تعرّض للكشف.
- افتراض أن الـ API مجانية. كثير من الـ APIs تتقاضى رسومًا على كل طلب أو على كل وحدة استخدام — وواجهات نماذج الذكاء الاصطناعي تحتسب بالرموز (tokens). تحقق من الأسعار وضع حدودًا للإنفاق. انظر كيفية استخدام واجهات LLM.
- عدم التعامل مع الفشل. الخدمات الخارجية تتوقف، وتنتهي مهلتها، وتصل إلى حدود الاستخدام. اطلب رسائل خطأ مناسبة وإعادة محاولة معقولة.
- الثقة بالمتصفح. يجب أن تتحقق واجهة API الخاصة بك من الصلاحيات بنفسها. إخفاء زر لا يمنع أحدًا من استدعاء نقطة النهاية مباشرة.
- استخدام مفاتيح حقيقية أثناء الاختبار. استخدم مفاتيح وضع الاختبار حتى تكون جاهزًا للإطلاق.
ماذا تطلب من منشئ التطبيقات بالذكاء الاصطناعي
- "ما واجهات API الخارجية التي يستخدمها هذا التطبيق، وكم تكلّف كل واحدة؟"
- "استدعِ واجهة الدفع من الخادم فقط. اقرأ المفتاح من متغير بيئة."
- "اعرض كل نقطة نهاية في واجهتنا، وما الذي تفعله، ومن يُسمح له باستدعائها."
- "تحقق على الخادم من أن المستخدم المسجّل يملك الحجز قبل تحديثه أو حذفه."
- "إذا فشلت واجهة البريد، احفظ الحجز على أي حال وسجّل الخطأ."
- "استخدم وضع الاختبار لدى المزود في الوقت الحالي."
واجهات API في Mythex
تستطيع Mythex بناء واجهة API خاصة بك — سواء كجزء من تطبيق ويب، أو كخادم خلفي منفصل بلغة Node أو Python (FastAPI) أو C# أو Java يعمل إلى جانب الواجهة الأمامية — وكتابة الكود الذي يستدعي الخدمات الخارجية. تضيف مفاتيحها كأسرار للمشروع بدلًا من وضعها في المحادثة، وتكون متاحة لتطبيقك في المعاينة وبعد النشر. وتحتوي الوثائق على وصفات لـدمج أي API وبناء خادم REST خلفي.
الأسئلة
ما هو API ببساطة؟
الـ API (واجهة برمجة التطبيقات) طريقة محددة يطلب بها برنامج من برنامج آخر بيانات أو يطلب منه تنفيذ شيء ما. يرسل تطبيقك طلبًا بصيغة متفق عليها، فيعيد النظام الآخر ردًا — كبيانات الطقس، أو نتيجة دفعة، أو رد يولّده الذكاء الاصطناعي.
ما هو REST API؟
واجهة REST نمط شائع لواجهات الويب، حيث يكون لكل نوع من الأشياء (الحجوزات، العملاء) عنوان URL، وتستخدم طرق HTTP القياسية — GET للقراءة، وPOST للإنشاء، وPUT أو PATCH للتحديث، وDELETE للحذف. وعادةً ما تعود البيانات بصيغة JSON.
ما هو مفتاح API وأين أحتفظ به؟
مفتاح API سلسلة سرية تعرّف تطبيقك للخدمة، وغالبًا ما يسمح له بإنفاق المال أو الوصول إلى البيانات. احفظه في متغيرات البيئة أو في أسرار المشروع على الخادم، ولا تضعه أبدًا في كود يعمل داخل المتصفح ولا في مستودع عام.
ما الفرق بين API وWebhook؟
مع الـ API، يسأل تطبيقك خدمة أخرى عن شيء عندما يحتاج إليه. ومع الـ Webhook، تستدعي الخدمة الأخرى تطبيقك عندما يقع حدث ما — مثلًا عندما يخبرك مزود الدفع بنجاح دفعة.