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

ما الواجهة البرمجية (API) ببساطة؟

اسمها المختصر لـ Application Programming Interface. وأسهل تشبيه أنها نادل المطعم:

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

كيف يعمل نمط REST الأشهر؟

أغلب الواجهات على الويب تتبع أسلوبًا يسمى REST، وهو مجموعة اتفاقيات لا بروتوكول صارم:

الموارد: كل شيء يمثل مواردًا لها عناوين، مثل /products لقائمة المنتجات و/products/42 لمنتج بعينه. وتسمى بأسماء جمع وليس بأفعال.
طرق HTTP للأفعال: GET للقراءة، وPOST للإنشاء، وPUT أو PATCH للتعديل، وDELETE للحذف. فالفعل يعبر عنه الطريق لا المسار.
عدم حفظ الحالة: كل طلب يحمل ما يلزم لفهمه، ولا يعتمد الخادم على ذاكرة عن الطلبات السابقة. وهذا يسهل التوسع.
تمثيل البيانات: تُرسل الموارد بصيغة شائعة هي JSON غالبًا، وفيها كائنات وقوائم مألوفة لمبرمجي جافاسكربت وغيرهم.
رموز الحالة: 200 للنجاح و201 للإنشاء و204 بلا محتوى و400 للطلب الخاطئ و401 لغير المصادق و403 للممنوع و404 لغير الموجود و429 لكثرة الطلبات و500 لخطأ الخادم.
المعاملات: معاملات الاستعلام في العنوان للتصفية والترتيب والترقيم، مثل /products?category=books&page=2.
تدرج الواقع: كثير من الواجهات تسمى REST وهي تخالف بعض القواعد، فلا تتعجب إن لم تجدها نقية، وركز على الوضوح والاتساق.

ما أنماط الواجهات الأخرى؟

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

GraphQL: يتيح للمستهلك تحديد الحقول التي يريدها بالضبط في طلب واحد، فيقلل الإفراط في البيانات. يناسب واجهات معقدة، لكن له كلفة في التنفيذ والتخزين المؤقت.
gRPC: إطار اتصال سريع بين الخدمات يعتمد صيغة ثنائية وتعريفات صارمة، شائع بين الخدمات الداخلية في الأنظمة الكبيرة.
WebSockets: اتصال مفتوح ثنائي الاتجاه للتحديثات الفورية كالمحادثات والأسعار المباشرة، فلا ينتظر العميل أن يسأل.
Webhooks: بدل أن تسأل الخدمة كل دقيقة، تنادي الخدمة عنوانًا عندك حين يقع حدث، كنجاح دفعة. وتحتاج إلى التحقق من هوية المرسل.
SOAP: قديم يعتمد XML، ما زال في أنظمة مؤسسية وحكومية قائمة.
الأحداث المرسلة من الخادم (SSE): بث أحادي الاتجاه من الخادم إلى المتصفح، أبسط من WebSockets لبعض الحالات.
الاختيار: ابدأ بـ REST ما لم تكن لديك حاجة محددة، فهو الأكثر شيوعًا والأوفر في الموارد.

كيف تستهلك واجهة موجودة؟

أغلب مبتدئي الواجهات يبدؤون مستهلكين. وهذه خطوات منظمة للتعامل مع أي واجهة جديدة:

اقرأ التوثيق: المسارات والمدخلات والمخرجات وأمثلة الطلبات وشروط الاستعمال. فالتوثيق الجيد يختصر الأيام.
جرب بأداة: مثل Postman أو Insomnia أو أمر curl قبل كتابة كود، فتتأكد أنك تفهم الطلب والرد.
المصادقة: معظم الواجهات تتطلب مفتاحًا أو رمزًا يُرسل في الترويسة. لا تضعه في كود الواجهة الأمامية الذي يراه الجميع، بل مرره عبر خادمك.
اكتب الطلب في كودك: في جافاسكربت بدالة fetch، وفي بايثون بمكتبة requests أو httpx، وهكذا. وحوّل الرد من JSON إلى كائنات.
تعامل مع الأخطاء: تحقق من رمز الحالة، وتوقع فشل الشبكة والمهلات، وقدم رسالة مفهومة للمستخدم.
احترم حدود الاستعمال: كثير من الواجهات تحدد عدد الطلبات المسموحة، فاستعمل التخزين المؤقت وتجنب الطلبات الزائدة وأعد المحاولة بتأنٍّ عند الرفض.
لا تفترض ثبات الرد: قد تتغير الحقول مع الإصدارات، فتحقق من وجود الحقل قبل استعماله وتابع إعلانات التغيير.
اقرأ شروط الخدمة: بعض الواجهات تقيد الاستعمال التجاري أو تخزين البيانات.

كيف تصمم واجهة جيدة لتطبيقك؟

حين تبني واجهتك، فمن سيستهلكها قد يكون أنت بعد ستة أشهر، فاجعلها واضحة:

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

ما الأخطاء الشائعة مع الواجهات؟

بعض الأخطاء تتكرر في التصميم والاستهلاك على السواء، وتجنبها يوفر عليك وقتًا كبيرًا:

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

أسئلة شائعة عن واجهات API

ما الفرق بين API وWeb Service؟

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

هل JSON هو الصيغة الوحيدة؟

لا. هو الأشهر، وتوجد XML وصيغ ثنائية وغيرها. اختر ما يناسب مستهلكيك، والأغلب JSON.

كيف أتدرب على الواجهات؟

استهلك واجهات عامة مجانية لعرض بيانات، ثم ابنِ واجهة صغيرة لقائمة مهام بقاعدة بيانات، ثم اربطها بواجهة أمامية. فتفهم الطرفين.