REST API أم WebSocket

توفّر WLTE كلًا من REST API وWebSocket. لا يحل أحدهما محل الآخر: إنهما قناتان صُممتا لاحتياجات تكامل مختلفة.

النموذج الأساسي

تستخدم REST API نموذج الطلب/الاستجابة القياسي. يرسل خادمك طلب HTTPS واحدًا، وتُعيد WLTE استجابة صريحة واحدة. مناسبة لسرد الموارد، والاستعلام عنها، وإرسال العمليات، وقراءة نتائجها.

يستخدم WebSocket نموذج اتصال مستمر. ينشئ خادمك أولًا wsTicket أحادي الاستخدام عبر REST، ثم يُنشئ اتصال wss. بعد إنشاء الاتصال، يمكن استخدام الاتصال نفسه لإرسال الطلبات واستقبال أحداث الجهاز.

الفروق الرئيسية

البُعد	REST API	WebSocket
الاتصال	طلب HTTP مستقل لكل استدعاء	اتصال مستمر يُعاد استخدامه عبر الزمن
التفاعل	طلب واحد، استجابة واحدة	إرسال طلبات، واستقبال ردود، واستقبال أحداث
الأنسب لـ	القوائم، والتقسيم إلى صفحات، والإعداد، وإرسال الأوامر، والاستعلام عن النتائج	الاستعلامات الفورية عن الحالة، والتفاعل منخفض الكمون، وتسليم الأحداث
نموذج الموثوقية	لكل طلب نتيجة صريحة ويمكن أن يتبع قواعد إعادة محاولة HTTP	قد ينقطع الاتصال؛ لا ضمان لإعادة تشغيل الأحداث التي وقعت أثناء الانقطاع
التفويض	يتحقق كل نقطة نهاية محمية من الصلاحيات الحالية	يتطلب الاتصال تذكرة (ticket)؛ ولا تزال الطلبات النشطة تتحقق من صلاحيات العملية
حماية الطلبات	الاستعلامات وعمليات الأجهزة محدودة المعدل	الاتصالات والرسائل وعمليات الأجهزة محدودة المعدل
تكلفة التكامل	أبسط، مناسبة لمعظم تكاملات الخادم	أكثر تعقيدًا: تتطلب نبض قلب (heartbeat)، وإعادة اتصال، ومعالجة أحداث تماثلية (idempotent)

متى تستخدم REST API

يُفضَّل استخدام REST API عندما تحتاج إلى:

• عرض أجهزة حساب معيّن
• تحميل الأجهزة مع تقسيم إلى صفحات
• قراءة تعريفات نوع الجهاز
• إنشاء عمليات مرحّل أو RS485 أو إعداد
• الاستعلام عن نتيجة أمر
• تشغيل مزامنة مجدولة من جانب الخادم
• العمل برموز حالة HTTP ورموز أخطاء عمل واضحة

التدفق النموذجي:

الحصول على access token
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

متى تستخدم WebSocket

فكّر في WebSocket عندما يحتاج خادمك إلى:

• البقاء متصلًا واستقبال أحداث الجهاز
• الاستعلام عن الحالة الفورية لجهاز واحد بكمون منخفض
• الحفاظ على حالة الأجهزة حيّة داخل عملية خدمة (service process)
• تقليل الكمون الناتج عن إنشاء اتصالات HTTP متكررة

التدفق النموذجي:

الحصول على access token
-> POST /wlte/v1/ws/ticket
-> الاتصال بـ wss://.../wlte/v1/ws?ticket=...
-> إرسال session.ping كنبض قلب للتطبيق
-> إرسال device.state.get للحصول على الحالة الفورية لجهاز واحد
-> إرسال device.operation.execute لتنفيذ عمليات الجهاز
-> استقبال أحداث الجهاز

المزيج الموصى به

يجب أن تستخدم معظم تكاملات الإنتاج كليهما:

1. استخدم REST API للتهيئة الأولية والمزامنة الاحتياطية.
2. استخدم WebSocket للتغيّرات الفورية واستعلامات الحالة الفورية لجهاز واحد.
3. بعد انقطاع WebSocket أو إعادة تشغيل الخدمة، استخدم REST API لإعادة بناء خط أساس الحالة.
4. لا تعتمد فقط على أحداث WebSocket بالنسبة لحالة العمل الحرجة: احرص دائمًا على أن يكون بإمكانك تأكيدها عبر REST API.

الأخطاء الشائعة

تحديث جميع أجهزة الحساب عبر WebSocket

غير موصى به. device.state.get مخصص للحالة الفورية لجهاز واحد وقد يُطلق تحديثًا فعليًا وحدود معدل خاصة بكل جهاز. لسرد أجهزة حساب معيّن استخدم سرد الأجهزة (بالإنجليزية).

افتراض أن WebSocket لا ينقطع أبدًا

لا تفترض ذلك. يمكن أن تُغلق تغيّرات الشبكة، وعمليات النشر، والوسطاء (proxies)، وإعادة تشغيل الخدمة، وإعادة تشغيل عملية العميل الاتصال. يجب أن ينفّذ العميل إعادة الاتصال، ونبض القلب، ومعالجة أحداث تماثلية.

استبدال جميع استعلامات الحالة بأحداث WebSocket

غير موصى به. WebSocket مخصص للإشعار الفوري، لكن يجب ألّا يكون المصدر الدائم الوحيد للحالة. بعد فجوة في الحالة، أو إعادة تحميل الصفحة، أو إعادة تشغيل الخدمة، أكّد الحالة مجددًا عبر REST API أو باستخدام device.state.get.

جدول قرار سريع

الحاجة	التوصية
التكامل الأول أو التحقق من صحة API	REST API
عرض قائمة أجهزة	REST API
يفتح المستخدم تفاصيل جهاز واحد ويحدّثها	REST API عبر GET /devices/{deviceId} أو WS عبر device.state.get
يحتاج الخادم إلى أحداث تغيّر مستمرة	WebSocket
تنفيذ التحكم في جهاز	REST API، أو device.operation.execute على اتصال WebSocket مفتوح بالفعل
الاستعلام عن النتيجة النهائية لأمر	REST API
استرداد الحالة بعد انقطاع WebSocket	أعِد المزامنة عبر REST API ثم تابع مع WebSocket