آمل توضيح متى ولأغراض أيّ الغرضين يعمل نظاما مصادقة Discourse API.
(من هنا). هذا هو أفضل فهم لدي:
يمكن استخدام Admin API، ويُشار إليها أحيانًا باسم JSON API، عندما ترغب في إجراء مكالمات API للتفاعل مع منتدى Discourse، سواء:
- لم تكن هذه المكالمات تتطلب أي مصادقة، أو
- كانت تتطلب مصادقة، لكنك تملك سيطرة مباشرة على منتدى Discourse أيضًا، مما يسمح لك بتوليد مفاتيح API يدويًا يمكن لمنتدىك و/أو التطبيق المنفصل استخدامها لإجراء مكالمات الـ API.
أما User API، فمن جهة أخرى، مخصص للحالات التي ترغب فيها بالتفاعل مع منتدى (أو منتديات) Discourse، وتتطلب هذه التفاعلات مصادقة، وأنت لا تملك السيطرة على المنتدى (أو المنتديات) التي ترغب بالتفاعل معها.
طريقة أخرى لصياغة ذلك: Admin API مخصصة عندما تسيطر على المنتدى الذي تتفاعل معه، بينما User API مخصصة عندما لا تسيطر على المنتدى.
هل هذا صحيح؟
على سبيل المثال، يذكر وصف @david هنا أن Admin API لا يُقصد استخدامها مع عملاء JavaScript. لكنني أعتقد أنه من المقبول استخدام Admin API مع عملاء JavaScript طالما أن مالك التطبيق الذي يستخدمه عملاء JavaScript يسيطر أيضًا على المنتدى. (أي أن مالك التطبيق المنفصل هو نفسه مالك المنتدى). صحيح؟
أعتقد أن هذا هو كيفية عملها. إذا أردت إجراء مكالمات إلى Admin API بخصوص موقع Discourse من تطبيق منفصل، فأعتقد أنه يمكنك إجراء هذه المكالمات من جانب الخادم (من الخلفية). إذا لم تقم بها من جانب الخادم -بل من جانب العميل- فقد تواجه قيود CORS. في هذه الحالة، يمكنك إضافة نطاق التطبيق المنفصل إلى القائمة البيضاء في admin/site_settings/security/ → “cors origins”.
فيما يلي أيضًا تفاصيل أكثر حول كيفية عمل هذين الـ API. لدي سؤال آخر لا يزال معلقًا: عند إعداد مفتاح API لـ Admin API، متى يكون استخدام “جميع المستخدمين” كمستوى للمستخدم مناسبًا؟
تفاصيل إضافية:
Admin API
الأساسيات
هذا هو الـ API الموصوف في docs.discourse.org. يُشار إليه أحيانًا باسم JSON API.
من خلال التفاعل مع نقاط نهاية هذا الـ API، يمكنك فعل تقريبًا أي شيء يمكنك فعله مباشرة على موقع Discourse، باستخدام الطريقة الموصوفة هنا.
تتطلب بعض نقاط النهاية مصادقة. على سبيل المثال، إذا أردت استخدام الـ API لاسترداد تفاصيل مجموعة معينة (نقطة النهاية: [your-forum]/groups/[group-name].json)، لكن تلك المجموعة مرئية فقط لأعضائها، فستحتاج إلى إجراء المكالمة إلى نقطة النهاية “نيابةً عن” أحد الأعضاء.
لإجراء مكالمة الـ API باستخدام المصادقة الصحيحة، ستحتاج إلى توليد مفتاح API في [your-forum]/admin/api → New API Key، مع اختيار مستوى المستخدم “مستخدم واحد” لهذا المفتاح، واختيار مستخدم مُصرّح له بعرض المورد (مثل معلومات حول مجموعة).
عند إجراء مكالمة الـ API، قم بتضمين الرؤوس: المفتاح كـ Api-Key واسم المستخدم كمستخدم كـ Api-Username.
هناك أيضًا خيار، عند إعداد مفتاح API، لاختيار “جميع المستخدمين”. وفقًا لسؤالي أعلاه، لست متأكدًا متى يكون هذا مناسبًا مقارنةً باختيار مستخدم واحد وجعل هذا المستخدم هو المسؤول.
متى نستخدمه
يمكنك استخدام Admin API من “داخل” تطبيق Discourse. لذا يمكنك التفاعل مع Admin API: (i) من لوحة تحكم تعديل CSS/HTML لكل سمة تحت [your-forum]/admin/customize، (ii) من سمة تدمجها في موقع Discourse الخاص بك، و (iii) من إضافة (plugin) تدمجها في موقع Discourse الخاص بك.
يمكنك أيضًا استخدام Admin API من تطبيق منفصل، إذا كنت تسيطر على منتدى Discourse بحيث يمكنك، من خلال المنتدى، توليد مفتاح (مفاتيح) API يدويًا ستستخدمه التطبيق المنفصل.
وفقًا لسؤالي أعلاه، هذا هو الفهم الذي آمل تأكيده.
User API
تفاصيل هذا الـ API موصوفة هنا: User API keys specification
أعتقد أن User API موجود لأن Admin API لا يُقصد استخدامها كـ API عام يمكن لأي موقع أو تطبيق منفصل عن المنتدى الوصول إليه.
وللتوضيح: هناك سيناريوهان مختلفان حيث قد يتفاعل تطبيق منفصل مع منتدى Discourse الخاص بك:
السيناريو 1: لا يوجد اتصال مباشر: مطور غير متصل بمنتدى Discourse ينشئ تطبيقًا يتفاعل مع المنتدى. على سبيل المثال، مطور ليس مسؤولاً عن المنتدى أو غير متصل بأي طريقة بمسؤولي المنتدى يريد إنشاء تطبيق يستطلع مواقع Discourse مختلفة للحصول على بعض الحقائق عنها أو معلومات منها.
في هذا السيناريو، لن يقوم مسؤول منتدى Discourse بتوليد مفتاح API يدويًا لإعطائه للمطور غير المتصل. لذا فإن Admin API غير مناسبة.
لذلك، تمامًا مثل العديد من المواقع مثل YouTube التي لديها API يمكن للمطورين من جهات خارجية استخدامها للتفاعل مع YouTube في التطبيقات التي يصنعونها، فإن User API الخاص بـ Discourse هو وسيلة للتطبيقات من جهات خارجية للتفاعل مع منتدى الخاص بك من خلال قيام العملاء (أجهزة سطح المكتب، الهواتف المحمولة) الذين يستخدمون التطبيقات بتوليد مفتاح API يمنحهم وصولاً محدودًا إلى المنتدى.
السيناريو 2: تطبيق متصل مباشرة: مسؤول منتدى (أو مطور متصل بمسؤول) متصل بتطبيق منفصل يريد المسؤول التفاعل مع المنتدى.
على سبيل المثال، ربما يريد المسؤول وجود تطبيق منفصل بميزات غير موجودة في Discourse، ويريد وجود تداخل بين مستخدمي التطبيق المنفصل والمنتدى. في هذه الحالة، يمكن للمسؤول فعليًا توليد مفاتيح API مباشرة (يدويًا من خلال لوحة تحكم المسؤول في المنتدى) وتقديمها للتطبيق المنفصل لاستخدامها، بحيث يمكن للتطبيق المنفصل استخدام Admin API.