أبحث عن طريقة للحصول على قائمة نهائية بنقاط نهاية واجهة برمجة التطبيقات (API) المتوفرة في مثيل Discourse الخاص بي. قد يكون من الصعب أحيانًا معرفة واجهات برمجة التطبيقات المتاحة لي عند التطلع إلى بناء تكامل مع المنصة.
5 إعجابات
لا أعتقد أن هذا ممكن تقنيًا. لا يمتلك Discourse مسارًا لاكتشاف واجهة برمجة التطبيقات (API) (على سبيل المثال، شيء مشابه لمسار WordPress /wp-json). أقرب شيء أعرفه هو الوثائق الموجودة على https://docs.discourse.org/.
بالنسبة للتكاملات التي لا تغطيها الوثائق، ربما تكون أسرع طريقة لمعرفة ما إذا كان يمكن تحقيقها هي السؤال هنا حول كيفية تحقيق هدف معين. القاعدة العامة مع واجهة برمجة التطبيقات (API) هي أن أي شيء يمكن القيام به من خلال واجهة مستخدم Discourse يمكن القيام به أيضًا عبر واجهة برمجة التطبيقات (API).
9 إعجابات
أقدر ردك يا سيمون! أنا على دراية بـ docs.discourse.org (والذي، بشكل غريب، ليس الوثائق الرسمية ولكن مواصفات واجهة برمجة التطبيقات).
أنا أيضًا على دراية باستخدام وحدة تحكم المتصفح الخاصة بي لالتقاط الطلبات وكذلك تصفح ملفات routes.rb.
كما يمكنك أن تتخيل، فإن الخيارين أعلاه مملان للغاية وليسا سهلين الاستخدام. بالنسبة لأولئك منا الذين يتطلعون إلى بناء تكاملات عميقة بسرعة - خاصة إذا كان لدينا فرق أخرى في أعمالنا أو بائعون خارجيون يرغبون في التكامل… فإن إخبارهم بالقيام بالأشياء المذكورة أعلاه قد أدى إلى استجابة سيئة للغاية.
بينما أنا على دراية بالمرونة في قدرات Discourse، فإن التطوير على المنصة أو التكامل معها يمثل معركة شاقة، في أقل تقدير. كجهد أخير، كنت آمل أن تكون هناك طريقة برمجية لتجميع واجهات برمجة التطبيقات العامة.
7 إعجابات
المصدر النهائي، بخلاف المصدر هو هندسة عكسية لواجهة برمجة تطبيقات Discourse.
كل ما يمكنك فعله في الواجهة الأمامية يمكنك القيام به باستخدام واجهة برمجة التطبيقات. هناك عدد قليل جدًا من الأشياء التي يمكنك القيام بها باستخدام واجهة برمجة التطبيقات فقط.
3 إعجابات
هل يمكنك توضيح ما تقصده بهذا بشكل أكبر؟
بينما نقطة سيمون حول عدم تغطية هذه الواجهات البرمجية التي يتم تنفيذها عن طريق ملحقات لـ Discourse (مثل الإضافات)، فإن هذه الوثائق رسمية بمعنى أننا نحافظ عليها.
هذا لا يعني أن لدينا مجالًا كبيرًا للتحسين عندما يتعلق الأمر بتوثيق واجهة برمجة التطبيقات من جانب الخادم، وواجهة برمجة التطبيقات نفسها، ولكني أردت أن أفهم ملاحظاتك حول الوثائق الموجودة هناك بشكل أفضل.
إعجاب واحد (1)
بالتأكيد! هذا ربما أكثر مما طلبته 
أعتقد أنك تحتفظ بتوثيق منتجك الرسمي هنا، صحيح؟
أود أن أقول إن الفارق الدقيق هو أن مواصفات واجهة برمجة التطبيقات (API) هي مجموعة فرعية من التوثيق. لذلك أنسى دائمًا ويلتقطني ذلك للحظة عندما أشير إلى شخص ما إلى docs.discourse.org وأنسى أن هذا الرابط لا يؤدي إلى توثيق Discourse… بل يؤدي إلى مجموعة محدودة من مواصفات واجهة برمجة التطبيقات.
لذا أقول لهم صيغة من هذا القبيل:
شكرًا على الاجتماع اليوم، يسعدني اهتمامك بمعرفة نوع التجربة التي يمكنك بناؤها لمستخدمينا باستخدام Netwrix Community الجديد!
التوثيق موجود بالفعل في https://meta.discourse.org/c/documentation/10.
docs.discourse.org ليس في الواقع توثيقهم، بل مواصفات واجهة برمجة التطبيقات الخاصة بهم. أعرف أنك سألت عن التكامل مع المجتمع الجديد الذي نبنيه. للأسف ليس لدي صفحة يمكنني أن أشير إليها تظهر كل الوظائف التي تقدمها Discourse، ولكن يمكنك الذهاب إلى docs.discourse.org للحصول على فكرة عن بعض ما هو ممكن.
ما أفعله في هذا السيناريو، نظرًا لعدم قدرتي على تزويدهم بقائمة محددة من نقاط النهاية الموجودة، هو أنني أقول لهم ببساطة: “افترض أن كل ما يمكنك تخيله ممكن. سأذهب وأرى ما يمكن أن تفعله Discourse، وسنقلصها من هناك إذا احتجنا إلى ذلك.”
ولكن سيكون من الرائع لو تم إدراج جميع واجهات برمجة التطبيقات في المواصفات، أليس كذلك؟
مزيد من السياق…
سيكون الأمر غريبًا إذا اشتريت سيارة وقدموا لي ورقة بالميزات وسألت: “رائع! هل هذا كل شيء إذن؟”
“حسنًا، لا… ولكن إذا نظرت تحت غطاء المحرك وتتبعت بعض الأسلاك 12 فولت ومشابك الخراطيم حول المحرك، فيجب أن تكون قادرًا على رؤية ما تتصل به وهندسة عكسية لما يفعله الآخر.”
بالتأكيد، يمكن للميكانيكي/المطور/الأشخاص ذوي التفكير التقني في هذا السيناريو القيام بذلك. ولكن ليس الجميع 
أيضًا، حتى كمطور، لا أريد أن:
- أتعلم Ruby لمعرفة أين يمكن أن توجد المسارات
- أقوم بهندسة عكسية لجميع ملفات routes.rb للحصول على فكرة عن نقاط النهاية المتاحة
- أزيد من تحسين هذه الهندسة العكسية لمعرفة المدخلات التي تتطلبها، وهيكل الكائن للإخراج
- أبحث عن الإضافات التي لدي أيضًا
- أكرر ذلك على ملفات routes.rb الخاصة بهم (أعتقد؟ لا أعرف Ruby، لذلك لست متأكدًا حقًا)
- … وبعد 6 أشهر بين وظيفتي اليومية وهذا، لدي إجابة.
أقول كل هذا بمودة - لا يوجد منصة اليوم تضاهي إمكانيات منصة Discourse. نقطة. إنها المنتج الأقوى والأكثر فعالية ومرونة وفعالية من حيث التكلفة في السوق وتتفوق بفارق كبير على المنافسين.
عيوبها ليست في قوتها وقدرتها ومرونتها. في الواقع، هذه بعض من أكبر مزايا Discourse التي سيواجه المنتجات التنافسية صعوبة أو حتى فشل في محاكاتها.
- ليس الأمر أن واجهات برمجة التطبيقات الخاصة بها ليست رائعة - بل هو صعوبة العثور عليها.
- ليست لوحات الإدارة ذات الخيارات العديدة التي تجعل التبني صعبًا، بل نقص التعليم وأسماء إعدادات المسؤول مثل
First post onlyالتي تكون غامضة في أحسن الأحوال. - ليس تطبيقها القوي والبسيط (وبشكل مثالي!) لهيكل أداة المجتمع المكون من فئات ومواضيع وعلامات، ولكن المعلومات غير موجودة لتثقيف وإلهام المستخدمين بأنها لا يجب أن تكون فئة، بل مدونة، أو لوحة إعلانات للمنتج، أو بوابة أفكار… وأنها لا يجب أن تكون مواضيع بل يمكن أن تكون مدونات، وإعلانات منتجات، وأفكار.
هذا هو الشيء الوحيد الذي تفتقر إليه Discourse كمنتج بالنسبة لي: اللمسة النهائية - التفاصيل النهائية.
9/10، سأشتري مرة أخرى.
7 إعجابات
حسنًا، أعتقد أنني أفهم بشكل أفضل، شكرًا لك.
ما يلي هو آراء شخصية - لم أقم بمراجعتها مع أشخاص أكثر معرفة مني، لذلك قد يتم تصحيحي في بعض الأشياء التي أخطئ فيها هنا.
توثيق قصصنا يتطور أيضًا. لقد أحرزنا تقدمًا كبيرًا، ولكن لا يزال هناك طريق طويل لنقطعه. اسمحوا لي أن أحاول تلخيص الأمر قليلاً.
أولاً، كنوع من النموذج الذهني عالي المستوى، سأصف الأشياء على هذا النحو:
- نقطة الدخول الرئيسية للتوثيق لدينا موجودة هنا، كما أشرت: Documentation - Discourse Meta
- بالنسبة لتوثيق المطورين، فهو هنا، أو ربما الأفضل من ذلك، هنا: Introduction to Discourse Development
- وثائق واجهة برمجة التطبيقات (API) هي مجموعة فرعية من وثائق المطورين، وتقع هنا: https://docs.discourse.org/
أود أن أسمي وثائق واجهة برمجة التطبيقات (API) “وثائق” بدلاً من “مواصفات”، لكنني أتفق على أنها لا تزال مجموعة فرعية من وثائق المطورين لدينا. عنوان URL لهذه الوثائق غريب… سيكون من المنطقي أكثر أن تعيش وثائقنا الكاملة هناك أو أن يكون هذا إعادة توجيه إلى https://meta.discourse.org/c/documentation/10، وأن يكون هناك علامة واضحة من Introduction to Discourse Development إلى وثائق واجهة برمجة التطبيقات (API).
وثائق المطورين لدينا تخضع هي نفسها للتحسينات. ربما يروي سجل الالتزام هنا أفضل قصة حول أين ذهب الجهد حتى الآن: Commits · discourse/discourse-developer-docs · GitHub
يمكن وصف وثائق واجهة برمجة التطبيقات (API) بأنها غير مكتملة، ولكن لدينا عمل للقيام به لتوضيح قصتنا هنا. في الماضي، كنا نشير إلى “هندسة واجهة برمجة التطبيقات عكسيًا”، لكنني أتفق على أن هذه ليست قصة جيدة. إنها جيدة للقرصنة على مسؤوليتك الخاصة، ولكن قد تكون هناك حالات تكون فيها نقاط النهاية غير المدرجة هناك أفضل عدم الاعتماد عليها.
تم تصميم واجهة برمجة التطبيقات (API) من جانب الخادم في المقام الأول ليتم استهلاكها بواسطة تطبيق الواجهة الأمامية لدينا. في الواجهة الأمامية، نوفر واجهة برمجة تطبيقات JavaScript (JavaScript API) ستكون واجهة أفضل للاستهلاك لأنها يمكن أن تخفي التغييرات التي تم إجراؤها على الواجهة الخلفية: Using the JS API
إذًا، ما هي ضمانات الاستقرار التي يمكننا تقديمها بشأن واجهة برمجة التطبيقات (API) للواجهة الخلفية لدينا؟
أعتقد أن هذه مسؤولية يجب أن تعالجها وثائق واجهة برمجة التطبيقات (API) تلك. من الناحية المثالية، ما هو موثق هناك هو مجموعة فرعية من جميع نقاط النهاية التي ندعمها، ولكن مجموعة فرعية متعمدة نهدف إلى دعمها للآخرين الذين يبنون تكاملات، بينما الأشياء غير المدرجة هناك هي عن قصد غير موثقة على أنها أشياء مخصصة فقط لواجهة الواجهة الأمامية لدينا، والتي قد تتغير دون إشعار.
من الناحية المثالية (في ذهني)، سيكون لدينا توثيق مدمج في الكود المصدري بطريقة تكون فيها الوثائق نفسها قيد الاختبار، وقابلة للتوسيع باستخدام الإضافات، ويتم تقديمها بواسطة التطبيق نفسه بحيث تكون متزامنة مع المثيل الذي يتم توثيقه - بهذه الطريقة يمكنك عرض وثائق واجهة برمجة التطبيقات (API) لموقع معين ورؤية وثائق للإصدار الذي يعمل به، مع أي إضافات مثبتة وممكّنة بالفعل.
أعلم أن الآخرين داخليًا أجروا العديد من المناقشات حول أفكار أخرى لتحسين قصة واجهة برمجة التطبيقات (API) من جانب الخادم لدينا.
لم نتمكن من تحديد أولويات الكثير في هذا المجال بعد، حيث كان تركيزنا الأساسي عندما يتعلق الأمر بتجربة المطور خلال العامين الماضيين على تحديث واجهتنا الأمامية.
لست متأكدًا متى من المرجح أن يتغير ذلك، لكننا سنراقب الأشياء الصغيرة التي يمكننا القيام بها على طول الطريق لمواصلة العمل على قصة واجهة برمجة التطبيقات (API) من جانب الخادم. إذا كانت هناك أسئلة محددة تظهر، فربما يمكننا استخدامها كدافع لإجراء تحسينات أكثر استهدافًا في هذه الأثناء.
5 إعجابات
يجب معالجة ضمانات الاستقرار عن طريق الإصدار القياسي لواجهة برمجة التطبيقات.
هذا الموضوع ليس حول مكان وجود التوثيق - بل هو حول كيفية توثيق واجهة برمجة التطبيقات. ما هو مفقود هو تنسيق موحد وقابل للقراءة آليًا مثل OpenAPI.
هذا الغياب، إلى جانب الافتقار إلى الإصدار، يجعل عمل التكامل أصعب وأكثر هشاشة مما ينبغي. حتى مخطط OpenAPI أساسي لنقاط النهاية الموثقة سيكون مفيدًا للغاية.
3 إعجابات
في الأساس، هذه ليست مشكلة توثيق، بل هي مشكلة تنفيذ.
طرح @avdi هذا منذ سنوات وهناك إجماع داخلي واسع على أن المسار الصحيح للمضي قدمًا هو واجهة برمجة تطبيقات JSON/REST مناسبة ومُصنفة مع معلمات وأشكال متسقة للبيانات.
حاليًا، واجهة برمجة التطبيقات التي نقدمها هي واجهة برمجة التطبيقات الداخلية الخاصة بنا. إنها مكتملة وشاملة بنسبة 100%، ولكنها غير مريحة ومتغيرة الشكل. الأشكال التي تعيدها ونقاط النهاية مُحسّنة بالكامل لتشغيل تطبيق Ember من جانب العميل. إنها تتطور وتتغير أشكالها مع مرور الأشهر، مما يجعل الاعتماد عليها في المهام الحيوية أمرًا صعبًا. البناء عليها أكثر تعقيدًا مما ينبغي.
ستحل مجموعة جديدة تمامًا من وحدات التحكم والطرق مشكلة الاستقرار هنا وتسمح لنا بإعادة الأشكال التي تبدو منطقية أكثر لواجهة برمجة تطبيقات REST. على سبيل المثال:
/api/v0/topic/1234.json يمكن أن تعيد شكلاً أكثر “اتساقًا مع ممارسات واجهة برمجة التطبيقات العامة”.
هناك الكثير من “اهتمامات عميل Ember فقط” المعقدة للغاية في ملف JSON الخاص بالموضوع:
timeline_lookup و post_stream و tags_descriptions إلخ… إلخ…
ومع ذلك، هذا مشروع ضخم للشروع فيه، سنحتاج إلى الكثير من إعادة التصميم الداخلي لضمان عدم تكرار المنطق. بالإضافة إلى ذلك، تجعل الإضافات هذا الأمر أكثر تعقيدًا لأنها تعيد تشكيل الكثير من السلوك الداخلي الذي سيحتاج إلى انعكاس في واجهة برمجة التطبيقات. (ماذا يفعل التعيين لهذه الأشكال؟)
أنا بالتأكيد أرى أننا سنشرع في هذه المغامرة ولكن ليس في المستقبل القريب.
10 إعجابات
أعتقد أنه من المعقول تمامًا أن يستغرق التغيير وقتًا. لقد أدرت علاقات المطورين في شركتي الأخيرة يا إلهي… استغرق الأمر أكثر من عامين لكي نحسن حالة واجهات برمجة التطبيقات الخاصة بنا. هناك الكثير من الأمور المعقدة التي يجب النظر فيها (وكانت الهندسة تكره فكرة إنشاء نقطة نهاية مستقرة لا يمكن أن تتغير!)
لكن أعتقد أن التغييرات الصغيرة يمكن أن تحدث مع مرور الوقت وفي إطار زمني أقصر أيضًا. بصراحة، لم أبحث في كيفية تعريف مساراتك (أو كيفية تعريف المسارات في روبي) — لكني أرجح أن بعض الأمور السهلة يمكن التعامل معها بسهولة كبيرة. على سبيل المثال:
لا أستطيع الكلام باسم الجميع، لكن أعتقد أن وجود نقاط النهاية في مواصفات API الحالية لديك — حتى لو لم تكن هناك أوصاف وأمثلة، وحتى لو كان نموذج الاستجابة مرنًا — سيكون إنجازًا كبيرًا. فقط معرفة أن شيئًا ما موجود هو نصف المعركة أحيانًا.
5 إعجابات
هل وثائق واجهة برمجة التطبيقات بتنسيق OpenAPI؟
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 إعجابات
يجب أن أعترف بخجل أنني لم ألاحظ ذلك قط…
شكراً @blake على لفت انتباهي إلى ذلك.
إعجابَين (2)