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

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

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

تستخدم واجهات الويب بروتوكول HTTP كثيرًا. يحمل الفعل GET معنى طلب بيانات عادة، بينما يستخدم POST لإرسال مورد جديد، وPUT أو PATCH للتحديث، وDELETE للحذف وفق تصميم الواجهة. هذه أدوار متعارف عليها وليست سحرًا داخل الكلمات؛ الخادم هو الذي ينفذ السلوك، والتصميم الجيد يجعل هذا السلوك متوقعًا وموثقًا.

رمز حالة الاستجابة يقدم ملخصًا سريعًا. تقع الاستجابات الناجحة عادة ضمن فئة 2xx، وتشير 4xx إلى مشكلة مرتبطة بالطلب أو الصلاحية، بينما تدل 5xx على فشل لدى الخادم. لا ينبغي للتطبيق الاكتفاء بالرقم؛ يقرأ رسالة الخطأ ويعرض للمستخدم تصرفًا مفهومًا، مثل إعادة تسجيل الدخول أو تصحيح حقل ناقص.

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

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

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

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

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

## سؤال للنقاش

ما الفرق الذي لاحظته بين واجهة موثقة جيدًا وواجهة يصعب استخدامها، وما أول اختبار تضيفه عند دمج خدمة خارجية؟

## المراجع

- رابطة الشبكة العالمية W3C، معايير وتقنيات الويب.
- فريق هندسة الإنترنت IETF، مواصفات بروتوكول HTTP.
- المراجع الجامعية ووثائق REST المتعلقة بتصميم واجهات الخدمات.