5.3خدمات الويب وAPI REST والتبادلات
الأساسي في 30 ثانية
- API REST هي معيار التبادل: يستهلك ياسين API مورّد للأسعار ويكشف خدمة للطلبات القادمة من موقع التجارة الإلكترونية، بصيغة JSON عبر HTTP.
- مفردات REST تُتقن: URL، طرق GET/POST/PUT/DELETE، رمز مصادقة لا يُكتب في الكود أبدًا وأكواد إرجاع تُعالج دائمًا.
- المتانة أولًا: عدم الثقة بالبيانات الواردة أبدًا، وتوقع المهلات والاستئناف وطابور الانتظار والاتساق التكراري وتسجيل التبادلات.
حالة مصغّرة متسلسلة — ياسين يربط إدارته بـAPI الشركاء
يطوّر ياسين تطبيق إدارة شركة صغيرة لتجارة المعدات الكهربائية في وهران. لتجنب إعادة إدخال الأسعار، يستعلم API REST لمورّد: يعيد GET سعر مقال ومخزونه بصيغة JSON. ولموقع التجارة الإلكترونية للموزّع، يكشف بنفسه API تستقبل الطلبات بـPOST وتعيد حالتها. رمز المصادقة لا يُكتب في الكود: يُقرأ من معامل محمي. تُتحقق كل استجابة قبل التسجيل، لأن سعرًا صفريًا أو رمز مقال مجهولًا يجب ألا يدخل القاعدة أبدًا. وعندما يكون المورّد غير متاح، يذهب الطلب إلى طابور انتظار ويُعاد إرساله بمعرّف فريد لتجنب التكرار. يسجّل ياسين كل استدعاء: التاريخ، الاتجاه، الخدمة، كود الإرجاع وبيانات موجزة.
حالة مستقلة لهذا القسم: تعود في الدرس والمخطط والكود وتحدي 48 ساعة للقسم 5.3.
1. الاستهلاك والكشف
نادرًا ما يعيش تطبيق الإدارة معزولًا: يتبادل مع المحاسبة، ERP، موقع تجارة إلكترونية، بنك أو مورّد. خدمات الويب وAPI REST هي المعيار الحديث. استهلاك API يعني استدعاء خدمة بعيدة للحصول على بيانات أو إرسالها؛ وكشف API يعني نشر خدمتك لتستدعيها تطبيقات أخرى. تتم التبادلات غالبًا بصيغة JSON عبر HTTP. تبقى ملفات التبادل (CSV، XML، JSON، Excel) مفيدة للاستيراد والتصدير بالدفعات، والوصول المباشر إلى قاعدة أخرى ما زال موجودًا، لكن API REST هو النمط المفضّل للزمن الحقيقي.
2. مفردات REST
لاستدعاء API، يحدد ياسين URL الخدمة والطريقة: GET للقراءة، POST للإنشاء، PUT للتعديل، DELETE للحذف. المصادقة تعتمد غالبًا على مفتاح أو رمز: هذه الأسرار يجب ألا تُكتب في الكود أبدًا ولا تُعرض في جانب العميل. صيغة البيانات (JSON غالبًا) يجب تحليلها وتحويلها إلى كائنات مهنية. أخيرًا، أكواد الإرجاع تشير إلى النجاح أو خطأ مصادقة أو مورد غير موجود أو خطأ خادم: وتُعالج دائمًا. الكود 200 لا يضمن صحة البيانات، والكود 500 ليس سببًا للتخلي دون أثر.
3. المتانة والتتبع
الخدمة البعيدة ستكون غير متاحة أو بطيئة أو غير متسقة يومًا ما. ينطلق ياسين من هذا المبدأ ويتوقع مهلة انتظار واستئنافات متباعدة وطابور انتظار لعدم فقدان شيء ومعالجة غير متزامنة لعدم تعطيل المستخدم. الاتساق التكراري يمنع التكرار عندما يتكرر الإرسال: معرّف عملية فريد يتيح للخادم التعرّف على طلب عولج سابقًا. كل البيانات الواردة تُتحقق قبل التسجيل. أخيرًا، تُسجّل التبادلات: التاريخ، الاتجاه، الخدمة، كود الإرجاع، بيانات موجزة ومعرّف مهني. إنه الدليل الوحيد القابل للاستخدام عند نزاع مع شريك، وأفضل أداة لتشخيص عطل متقطع.
🔎 مثال ملموس — 🔎 مثال عملي — استهلاك API سعر المورّد
يجلب ياسين سعرًا ويرفض كل قيمة غير متسقة:
// Consommation de l'API prix fournisseur
sURL est une chaîne = "https://api.fournisseur.dz/articles/" + SAI_CodeArticle
sReponse est une chaîne = RESTEnvoie(sURL, "GET", gsJetonFournisseur)
SI sReponse = "" ALORS
Erreur("Service fournisseur indisponible")
RENVOYER Faux
FIN
oArticle est un dynamic ArticleAPI
JSONVersObjet(sReponse, oArticle)
SI oArticle.PrixHT <= 0 ALORS
Erreur("Prix reçu invalide")
RENVOYER Faux
FIN
RENVOYER Vraiالنتيجة: لا يدخل أي سعر صفري أو سالب إلى قاعدة ياسين.
المنعكس: الرمز يأتي من معامل محمي، لا من الكود المصدري أبدًا.
مفردات القسم
- API REST
- خدمة ويب تكشف موارد عبر URL وطرق HTTP، غالبًا بصيغة JSON.
مثال بسيط: يستعلم ياسين API المورّد للأسعار والمخزون.
ما ليس كذلك: نسخ التعرفات يدويًا في التطبيق.
رد فعل: API REST = تبادل موحّد في الزمن الحقيقي.
- طرق HTTP
- أفعال بروتوكول HTTP: GET (قراءة)، POST (إنشاء)، PUT (تعديل)، DELETE (حذف).
مثال بسيط: يستخدم ياسين GET للاطلاع وPOST لاستقبال طلب.
ما ليس كذلك: فعل كل شيء بفعل واحد دون تمييز الإجراء.
رد فعل: الطريقة تصف نية التبادل.
- رمز API
- سر مصادقة يُقدَّم عند كل استدعاء لإثبات هوية التطبيق.
مثال بسيط: يقرأ ياسين رمزه من معامل محمي.
ما ليس كذلك: كتابة الرمز صراحة في الكود أو في صفحة.
رد فعل: السر لا يُكتب في الكود أبدًا.
- الاتساق التكراري
- خاصية تبادل، إذا تكرر بالمعرّف نفسه، لا يُنشئ تكرارًا.
مثال بسيط: يضيف ياسين معرّف عملية فريدًا لكل طلب.
ما ليس كذلك: إعادة إرسال الطلب نفسه بعد انقطاع الشبكة.
رد فعل: الاتساق التكراري = استئناف دون تكرار.
- سجل التبادلات
- أثر مؤرخ للاستدعاءات: الاتجاه، الخدمة، بيانات موجزة، كود الإرجاع ومعرّف مهني.
مثال بسيط: يطلع ياسين على السجل لتشخيص سعر مرفوض.
ما ليس كذلك: عدم تسجيل أي تبادل والافتراض أن كل شيء بخير.
رد فعل: السجل هو الدليل وأداة التشخيص.
في التطبيق — عمليًا — التبادل مع أنظمة أخرى
- حدّد النمط الملائم: API REST للزمن الحقيقي، ملفات CSV/XML/JSON للدفعات، والوصول المباشر إلى قاعدة أخرى كحل أخير.
- لاستهلاك API، حدّد URL والطريقة (GET/POST/PUT/DELETE) والمصادقة وصيغة JSON، دون كتابة السر في الكود أبدًا.
- عالج دائمًا أكواد الإرجاع والأعطال (خدمة غير متاحة، تجاوز المهلة) باستئناف وطابور انتظار واتساق تكراري.
- تحقق من كل البيانات الواردة، وسجّل التبادلات، وتحقق من التزاماتك بشأن البيانات الشخصية المرسلة.
سكربت خطوة بخطوة — تسجيل تبادل (10 دقائق)
يتتبع ياسين كل استجابة من المورّد ليكون قادرًا على التشخيص والإثبات.
نسجّل ملخصًا إذا كانت البيانات ضخمة، لكن دائمًا المعرّف المهني الذي يربط التبادل بالطلب.
نموذج للنسخ واللصق — بطاقة تبادل API
// Fiche d'échange — Yacine
// Service : API fournisseur matériel électrique
// URL : https://api.fournisseur.dz/articles/{code}
// Méthode : GET
// Authentification : jeton lu dans ParametreSecurise("API_FOURNISSEUR")
// Format : JSON (ArticleAPI)
// Codes traités : 200, 401, 404, 429, 500
// Robustesse : délai 10 s, 3 reprises espacées, file d'attente
// Idempotence : NumeroOperation unique
// Journal : date, sens, service, code, données résuméesسعر المورّد
يستهلك ياسين API مورّد لتحديث الأسعار والمخزون.
طلب التجارة الإلكترونية
يكشف ياسين API بـPOST تستقبل طلبات الموقع الشريك.
تصدير محاسبي
ينتج ياسين ملف CSV للمحاسبة عندما لا تكون API متاحة.
الاستئناف بعد العطل
يضع ياسين الإرسالات في طابور انتظار ويعيد إرسالها بمعرّف فريد.
✓ ممارسات جيدة
- حماية رموز ومفاتيح API خارج الكود المصدري.
- التحقق من كل البيانات الواردة قبل التسجيل.
- توقع الاستئنافات وطابور الانتظار والسجل من أول تبادل.
✗ أخطاء شائعة
- كتابة سر في الكود داخل التطبيق أو صفحة.
- الثقة في الكود 200 دون التحقق من البيانات.
- إعادة إرسال طلب دون معرّف عملية وإنشاء تكرار.
النقاط الأساسية
- API REST تتبادل بـJSON عبر HTTP، في الاستهلاك كما في الكشف.
- URL والطرق والمصادقة وأكواد الإرجاع تشكل مفردات REST.
- الأسرار لا تُكتب في الكود أبدًا والبيانات الواردة تُتحقق.
- المهلات والاستئنافات وطابور الانتظار والاتساق التكراري والسجل تجعل التبادلات متينة.
تحدي 48 ساعة — طبّقه غدًا
مثل ياسين، استدعِ API عامة بـGET من مشروع WinDev صغير، وحلّل JSON وتحقق من حقل قبل تسجيله. أضف سجل تبادل (التاريخ، الخدمة، كود الإرجاع، بيانات موجزة) وحاكِ عطلًا بقطع الشبكة. تحقق من أن الطلب يذهب إلى طابور الانتظار وأن إعادة الإرسال لا تُنشئ تكرارًا.
- أستطيع شرح الفرق بين استهلاك API وكشفها.
- أعرف تسمية طرق HTTP وحماية رمز.
- أعرف جعل التبادل متينًا ومسجّلًا.
أسئلة شائعة
لماذا يجب تسجيل التبادلات مع الأنظمة الخارجية؟
لأن السجل، عند حدوث مشكلة، هو الدليل الوحيد على ما أُرسل واستُقبل ومتى. يتيح تشخيص بيانات خاطئة أو عطل متقطع أو تغيير غير معلن عند الشريك. يفيد أيضًا في الاستئناف بعد الحادث بمعرفة ما مرّ بدقة، وفي الرد على نزاع أو تدقيق. يسجّل ياسين التاريخ والاتجاه والخدمة وكود الإرجاع وملخص البيانات والمعرّف المهني (رقم الطلب أو الفاتورة). دون هذا المعرّف، يصعب ربط السجل بالعملية الحقيقية.
كيف نجعل التبادلات المعتمدة على خدمة خارجية متينة؟
بالانطلاق من مبدأ أن الخدمة ستكون يومًا غير متاحة أو بطيئة أو غير متسقة. يجب مهلة انتظار لعدم التعطيل إلى ما لا نهاية، واستئنافات متباعدة ومحدودة، وطابور انتظار للحفاظ على الطلبات غير المرسلة، ومعالجة غير متزامنة لعدم تعطيل المستخدم، ومعرّف عملية فريد لجعل الإرسال متسقًا تكرارًا. تُتحقق كل الاستجابات قبل التسجيل، ويُسجّل كل تبادل. يتوقع ياسين أيضًا إعلام المستخدم بوضوح عندما يؤجّل التبادل.
ماذا نفعل بالبيانات الواردة من API مورّد قبل تسجيلها؟