لا أفهم سبب عدم وجود توثيق كامل لجميع نقاط نهاية واجهة برمجة التطبيقات (API). فقد نُشر التوثيق الأصلي للجمهور في ديسمبر 2014، وها نحن بعد ست سنوات لا يزال التوثيق غير مكتمل.
ما السبب في ذلك؟ إن عدم وجود توثيق جيد، والاقتراح بعكس هندسة واجهة برمجة التطبيقات، يشكل عائقًا كبيرًا أمام المطورين الراغبين في استخدام الواجهة.
مع خالص التحية،
مطور محبط
هل يمكنك تقديم بعض الأمثلة حول ما تواجه صعوبة فيه أو ما تجده ناقصًا؟
هذا موضوع في وقته لأن لدي تحذيرًا على منتداي: «لقد اكتشفنا طلب API يستخدم طريقة مصادقة قديمة».
أود معرفة الطريقة الحالية التي يجب أن أستخدمها، ودليل خطوة بخطوة لتطبيقها من وجهة نظر مدير المنتدى.
ما وجدته هو مناقشات قديمة تربط إلى GitHub، وبصفتي شخصًا غير تقني، فإن الإشارات إلى الأكواد غير مفيدة لي. هل يمكن لأحد تقديم إرشادات بلغة بسيطة واضحة؟
يتم تغطية المصادقة الصحيحة على API في الوثائق، في أعلى الصفحة. باختصار، تحتاج إلى استخدام رؤوس HTTP لتوفير مفتاح API واسم المستخدم بدلاً من معلمات URL.
@justin مثال محدد لدي هو أنني أعمل ببطء على إطلاق غلاف برمجي بلغة بايثون لـ Discourse API، وأجد أن نقص التوثيق المناسب أمر ساحق. عليّ بالفعل اختبار كل نقطة نهاية (endpoint) يدويًا، لكن العديد من هذه النقاط إما غير موثقة أو موثقة بشكل غير صحيح.
يُذكر صراحةً في أعلى التوثيق أن واجهة برمجة التطبيقات (API) غير موثقة بالكامل. أود أن أعرف: لماذا؟
انظر إلى Reverse engineer the Discourse API
لماذا لا يكون كل حبة رمل على الشاطئ “مُوثَّقة بالكامل”؟ 
للاستفسار فقط، لماذا لا تدعم ببساطة ما هو مطلوب حتى تصل إلى متطلب جديد غير مدعوم، وعندها تعكس هندسته؟ هذا أسهل بكثير من السعي لتحقيق 100%، وغير مجدٍ تغليف استدعاءات لن تُستخدم أبدًا؟ خاصة وأنك ستدعم هدفًا متحركًا. هل تريد أن تجعل حياتك أسهل؟
أدرك أنه يمكن عكس هندسة هذا الأمر. الأمر محبط قليلاً الاضطرار إلى فعل ذلك. تم إنشاء واجهة برمجة التطبيقات بواسطة بشر يجب أن يعرفوا كيفية عملها، فلماذا لا يقوم هؤلاء البشر بكتابته ليتم إطلاع الآخرين عليه؟
لا أشعر أن هذا طلب كبير. التوثيق الجيد أمر بالغ الأهمية في أي مشروع.
هذه هي الخطة الحالية؛ لقد قمت بعكس جميع نقاط النهاية الموثقة في مستودعي الفرعي حاليًا في فرع التطوير، وقد وصلت إلى النقطة التي سأضطر فيها إلى البدء في الهندسة العكسية.
لقد بدأت بالفعل في المساهمة في https://github.com/discourse/discourse_api_docs/، لكنني أشك حقيقيًا في سبب ضرورة ذلك في مشروع راسخ كهذا.
مثل أي شيء آخر، الأمر يتعلق بالموارد والأولويات. واجهة الـ API ضخمة جدًا. تقنيًا، كل شيء يُعتبر واجهة API، فكل شيء يتم الوصول إليه عبر الـ API، ومن هنا تأتي فعالية الهندسة العكسية. لقد اخترنا توجيه وقتنا الهندسي المحدود نحو الإصلاحات والميزات والأداء وما إلى ذلك، بدلًا من التوثيق. يتحدد اتجاه منتجنا إلى حد كبير من خلال عملائنا ومجتمعنا. حسب علمي، لم يطلب أي عميل أبدًا تغطية 100% من توثيق الـ API. وعندما يسأل العملاء عن شيء مفقود أو غير واضح، فإننا نضيفه. لذلك، لم تكن التغطية بنسبة 100% أولوية.
في الوقت الحالي، يتم توثيق الـ API يدويًا. ومن الواضح أن هذه ليست طريقة مستدامة، لكنها ما لدينا حاليًا. إعادة هيكلة نظام توثيق الـ API ليتم إنشاؤه برمجيًا هي عنصر في قائمة “المهام”، لكنه غير مخطط له حاليًا لأي إصدار محدد، لذا لا يوجد جدول زمني لإكماله.