توجد عدة أدلة تغطي استخدامات أو تفسيرات مختلفة لواجهة برمجة التطبيقات (API).
يقدم هذا الدليل أمثلة عملية وشاملة حول كيفية استخدامها.
لا يُقصد من جميع أمثلة الكود في هذا الدليل أن تظهر أفضل الممارسات أو أن تُستخدم كما هي.
تم تجاهل أو تخطي العديد من عمليات التحقق ومعالجة الأخطاء وما إلى ذلك عمدًا للتركيز حصريًا على استخدام واجهة برمجة التطبيقات.
ما الغرض من استخدام واجهة برمجة التطبيقات (API)؟
تُنفذ معظم إجراءاتك في Discourse (مثل النشر، الإعجاب، تعديل الإعدادات، إلخ) باستخدام واجهة برمجة التطبيقات من خلال إرسال طلبات إلى نقطة نهاية[1].
على سبيل المثال، عند إنشاء موضوع في Meta، يتم إرسال طلب POST إلى https://meta.discourse.org/posts.json. يحتوي الطلب، من بين أمور أخرى، على اسم المؤلف والعنوان والتصنيف والوسوم ومحتوى منشورك.
يتم عادةً استخدام واجهة برمجة التطبيقات بشكل مخصص لتحقيق مهام أتمتة، وغالبًا بالتزامن مع خدمات أخرى مثل الويب هوك (webhooks)، والسكريبتات، والبرمجيات وواجهات برمجة التطبيقات التابعة لجهات خارجية.
لاستخدام واجهة برمجة التطبيقات، من إلزامي وجود بيانات اعتماد API. يمكن القيام بذلك بضع نقرات، باتباع هذا الدليل: Create and configure an API key
لا تنتظر أكثر، ودعنا ننتقل إلى مثال أولي لحالة استخدام واجهة برمجة التطبيقات. 
إنشاء موضوع شهري
في هذا المثال، سنستخدم curl و cron لإنشاء موضوع “محادثة حرة” شهري في منتداك. وهي ممارسة شائعة في المجتمعات عبر الإنترنت 
إنشاء مفتاح واجهة برمجة التطبيقات
اتبع دليل إنشاء مفتاح واجهة برمجة التطبيقات. اضبط مستوى المستخدم على مستخدم واحد.
سيكون المستخدم المختار هو مؤلف الموضوع الشهري.
ثم يمكنك اختيار نطاق عام (Global) أو نطاق مفصل (Granular)، وفي هذه الحالة يجب أن يحتوي على حد أدنى من صلاحية المواضيع → كتابة (write).
اكتب مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه. 
إنشاء أمر curl
من سطر الأوامر في خادمك، شغل هذا الأمر لترى ما إذا كان يعمل وما إذا تم إنشاء موضوع بشكل صحيح باستخدام curl وواجهة برمجة التطبيقات REST في Discourse مع مفتاح واجهة برمجة التطبيقات الخاص بك:
curl -X POST "https://your-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: YOUR_API_KEY" -H "Api-Username: YOUR_USERNAME" -d "{\"title\": \"Test topic creation with the API\", \"raw\": \"And here's the topic's content\", \"category\": CATEGORY_ID }"
استبدل:
your-discourse.comبنطاق منتداكYOUR_API_KEYبمفتاح واجهة برمجة التطبيقات الخاص بكYOUR_USERNAMEباسم المستخدم المختار لمفتاح واجهة برمجة التطبيقاتCATEGORY_IDبمعرف التصنيف الذي تريد نشر موضوعك فيه.
إذا تم تكوين كل شيء بشكل صحيح، فسيتم إنشاء موضوع اختبار جديد في منتداك، مثل:
تم إنجاز معظم العمل في هذه المرحلة! الآن نحتاج إلى تغيير عنوان ومحتوى الموضوع إلى شيء أكثر ملاءمة، وإعداد تكرار إنشاء الموضوع.
ابدأ بتغيير عنوان الموضوع من:
Test topic creation with the API
إلى:
Free talk of the month - $(date +\%B).
لنقم بنفس الشيء للمحتوى من:
Test topic creation with the API
إلى:
What have you appreciated the most and the less during $(date +\%B -d 'last month')?\nFeel free to share your feelings and provide ideas. 🙂
أنا أستخدم أمر Unix date لإدراج اسم الشهر الحالي في العنوان واسم الشهر السابق في المحتوى.
\n في المحتوى ينشئ سطرًا جديدًا.
يمكنك استخدام سطر الأوامر وتشغيل طلب curl المحدث. يجب أن يكون قد أنشأ موضوعًا جديدًا مثل هذا في منتداك:
إعداد الحدث المتكرر
سنقوم بإنشاء مهمة cron ستنفذ أمر curl في اليوم الأول من كل شهر. 
قم بتحرير ملف cron بالأمر التالي:
crontab -e
أدرج هذا السطر في نهاية الملف (استبدل محتوى الطلب حسب الحاجة) واحفظ التعديل.
0 0 1 * * curl -X POST "https://your-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: YOUR_API_KEY" -H "Api-Username: YOUR_USERNAME" -d "{\"title\": \"Free talk of the month - $(date +\%B)\", \"raw\": \"What have you appreciated the most and the less during $(date +\%B -d 'last month')?\nFeel free to share your feelings and provide ideas. 🙂\", \"category\": 4 }"
الجزء 0 0 1 * * يحدد الفترة الزمنية التي سيتم فيها تشغيل الأمر. يمكنك معرفة المزيد حول الصيغة هنا: https://crontab.guru
تم! سيقوم خادمك الآن بإنشاء موضوع “محادثة حرة” جديد في اليوم الأول من كل شهر، باستخدام واجهة برمجة التطبيقات REST في Discourse، وطلب curl، ومهمة cron. 
تغيير مخطط الألوان الخاص بموضوع تلقائيًا
دعنا نجعل موضوعنا الافتراضي يستخدم مخطط ألوان يتناسب مع الموسم الحالي 
سنستخدم Ruby للتعامل مع فحوصات الأشهر ومهمة cron لتنفيذ السكريبت.
يمكننا استخدام طرق أخرى غير Ruby و cron، لكن هذا الدليل يهدف أيضًا إلى إظهار كيفية استخدام واجهة برمجة التطبيقات مع أدوات مختلفة.
إعداد الموضوع ومخططات الألوان
اختر الموضوع الذي تريد تغيير مخطط ألوانه، واحصل على معرفه. ستجد المعرف في عنوان URL الخاص بالموضوع. على سبيل المثال، معرف هذا الموضوع هو 1:
أنشئ 4 لوحات ألوان، واكتب معرفاتها أيضًا.
هنا، معرف لوحة ألوان الخريف هو 17:
إنشاء السكريبت
قم بتثبيت Ruby على خادمك.
أنشئ ملفًا باسم seasons.rb. سأعتبر أنه موجود في ~/scripts/ لهذا المثال.
ضع المحتوى التالي في هذا الملف. سنقوم بإرسال طلب PUT إلى نقطة نهاية موضوعنا وإرسال حمولة تحتوي على معرف مخطط الألوان:
require 'net/http'
require 'json'
require 'date'
current_month = Date.today.month
color_scheme_id = case current_month
when 1..3 then 18 # Winter
when 4..6 then 15 # Spring
when 7..9 then 16 # Summer
else 17 # Autumn
end
uri = URI('https://your-discourse.com/admin/themes/THEME_ID.json')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, {
'Api-Key' => 'YOUR_API_KEY',
'Api-Username' => 'YOUR_USERNAME',
'Content-Type' => 'application/json'
})
request.body = JSON.generate({
"theme" => {
"color_scheme_id" => color_scheme_id
}
})
response = http.request(request)
استبدل:
your-discourse.comبنطاق منتداكYOUR_API_KEYبمفتاح واجهة برمجة التطبيقات الخاص بكYOUR_USERNAMEباسم المستخدم المختار لمفتاح واجهة برمجة التطبيقاتTHEME_IDبمعرف موضوعك. يمكنك العثور عليه في نهاية عنوان URL لصفحة إعدادات الموضوع.
على سبيل المثال،https://your-discourse.com/admin/customize/themes/38، معرف الموضوع هو38.
دعنا نجرب السكريبت يدويًا.
أولاً، اضبطه على مخطط ألوان غير موسمي في واجهة Discourse إذا لم يكن الأمر كذلك بالفعل.
ثم، شغل السكريبت بالأمر التالي:
ruby ~/scripts/seasons.rb
حدّث متصفحك. يجب أن يكون مخطط الألوان المستخدم من قبل موضوعك قد تغير.
آخر ما يجب فعله هو إنشاء مهمة cron ستنفذ هذا السكريبت في اليوم الأول من كل شهر عند كل تغيير موسم.
راجع المثال الأول إذا لم تتذكر كيفية إنشاء مهمة cron.
0 0 1 1,4,7,10 * ruby ~/scripts/seasons.rb
تم! سيبدأ منتداك الآن بارتداء ألوان جديدة في بداية كل موسم جديد!
استلام طلب ويب على خادم ويب واستخدام بياناته لتحديث موضوع في Discourse
هذا أكثر تعقيدًا!
أداتنا ستكون PHP، مما يعني أننا سنفترض أن لديك خادم ويب يعمل في مكان ما مع تثبيت PHP.
في هذا المثال، سنستقبل حمولة ويب هوك من Ko-Fi (خدمة تبرعات) في صفحة PHP، والتي ستستخدم بعد ذلك البيانات المستلمة لاستخدام واجهة برمجة التطبيقات في Discourse وتحديث عنوان ومحتوى موضوع.
على وجه التحديد، سيقوم بتحديث عنوان الموضوع بمبلغ التبرع والتاريخ، وإضافة سطر جديد إلى الجدول الذي يسجل التبرعات السابقة (وسيقوم حتى برفع الموضوع تلقائيًا 
):
في كل مرة يقوم فيها مستخدم بالتبرع، سترسل Ko-Fi[2] طلبًا إلى سكريبت PHP الخاص بنا.
إعداد Ko-Fi
قمت بإعداد التكوين في صفحة ويب هوك في Ko-Fi ببساطة عن طريق إضافة عنوان URL لملف PHP الخاص بي وكتابة رمز التحقق المخفي في قسم “متقدم”.
في حالة تبرع واحد، سترسل Ko-Fi حمولة مثل هذه إلى سكريبت PHP الخاص بنا:
data = {
"verification_token": "d8546b84-c698-4df5-9811-39d35813e2ff",
"message_id": "a499df4c-7bbb-4061-b4a6-8b9d969da689",
"timestamp": "2023-10-19T13:35:06Z",
"type": "Donation",
"is_public": true,
"from_name": "Jo Example",
"message": "Good luck with the integration!",
"amount": "3.00",
"url": "https://ko-fi.com/Home/CoffeeShop?txid=00000000-1111-2222-3333-444444444444",
"email": "jo.example@example.com",
"currency": "USD",
"is_subscription_payment": false,
"is_first_subscription_payment": false,
"kofi_transaction_id": "00000000-1111-2222-3333-444444444444",
"shop_items": null,
"tier_name": null,
"shipping": null
}
سنستقبل هذه الحمولة، ثم نستخرج المعلومات التي نحتاجها:
-
المبلغ (
3.00)، الذي سنقربه إلى عدد صحيح. -
الطابع الزمني (
2023-10-19T13:35:06Z)، الذي سنقوم بتنسيقه إلى تاريخ أكثر جمالية.
استلام حمولة Ko-Fi
أولاً، نضع الكود التالي في صفحة PHP الخاصة بنا لاستلام الطلب من Ko-Fi، حيث نتأكد من استلامنا لطلب POST وأن قيمة الرمز تطابق القيمة المعطاة في صفحة ويب هوك في Ko-Fi. نقوم أيضًا بتنسيق المبلغ والتاريخ كما ذكرنا سابقًا.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'YOUR_VERIFICATION_TOKEN') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
}
}
استبدل:
YOUR_VERIFICATION_TOKENبالرمز الذي قدمته Ko-Fi
تحديث عنوان الموضوع
الخطوة التالية هي تحديث عنوان موضوعنا. سنستخدم curl في سكريبت PHP الخاص بنا لإرسال طلب PUT إلى نقطة النهاية المناسبة.
$putData = json_encode(['title' => '🥳 New donation: ' . $amount . '€ on ' . $date]);
$ch = curl_init('https://your-discourse.com/t/test-new-topic/TOPIC_ID');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $putData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($putData),
'Api-Key: YOUR_API_KEY',
'Api-Username: YOUR_USERNAME'
]);
curl_exec($ch);
استبدل:
your-discourse.comبنطاق منتداكTOPIC_IDبمعرف الموضوع الصحيحYOUR_API_KEYبمفتاح واجهة برمجة التطبيقات الخاص بكYOUR_USERNAMEباسم المستخدم المختار لمفتاح واجهة برمجة التطبيقات
تحديث محتوى المنشور
لإمكانية إرفاق محتوى جديد بالمنشور الأول للموضوع، نحتاج أولاً إلى استرجاع محتواه الحالي بطلب GET.
$ch_get = curl_init('https://your-discourse.com/posts/POST_ID.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
استبدل:
POST_IDبمعرف المنشور الصحيح[3]
أخيرًا، نحتاج إلى تحديث محتوى المنشور بإضافة سطر جديد إلى الجدول مع المبلغ والتاريخ. سنقوم بذلك بطلب PUT.
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://your-discourse.com/posts/POST_ID');
curl_setopt($ch_put, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch_put, CURLOPT_POSTFIELDS, $putPostData);
curl_setopt($ch_put, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($putPostData),
'Api-Key: YOUR_API_KEY',
'Api-Username: YOUR_USERNAME'
]);
curl_exec($ch_put);
استبدل:
your-discourse.comبنطاق منتداكPOST_IDبمعرف المنشور الصحيحYOUR_API_KEYبمفتاح واجهة برمجة التطبيقات الخاص بكYOUR_USERNAMEباسم المستخدم المختار لمفتاح واجهة برمجة التطبيقات
الكود النهائي يبدو كالتالي:
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'YOUR_VERIFICATION_TOKEN') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
$putData = json_encode(['title' => '🥳 New donation: ' . $amount . '€ on ' . $date]);
$ch = curl_init('https://your-discourse.com/t/test-new-topic/TOPIC_ID');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $putData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($putData),
'Api-Key: YOUR_API_KEY',
'Api-Username: YOUR_USERNAME'
]);
curl_exec($ch);
$ch_get = curl_init('https://your-discourse.com/posts/POST_ID.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://your-discourse.com/posts/POST_ID');
curl_setopt($ch_put, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch_put, CURLOPT_POSTFIELDS, $putPostData);
curl_setopt($ch_put, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($putPostData),
'Api-Key: YOUR_API_KEY',
'Api-Username: YOUR_USERNAME'
]);
curl_exec($ch_put);
curl_close($ch);
curl_close($ch_get);
curl_close($ch_put);
} else {
http_response_code(403);
echo "Invalid verification token.";
}
} else {
http_response_code(405);
echo "Only POST requests are allowed.";
}
?>
دعني أؤكد مرة أخرى التحذير في بداية هذا الدليل 
تم تجاهل أو تخطي العديد من عمليات التحقق ومعالجة الأخطاء وما إلى ذلك عمدًا للتركيز حصريًا على استخدام واجهة برمجة التطبيقات.
يمكننا الآن تشغيل طلب اختبار من Ko-Fi، ورؤية كيف يقوم بتحديث موضوعنا، كل من العنوان والمحتوى.
هذا كل شيء!
لديك موضوع سيتم تحديثه ورفع مرتبته في كل مرة يقوم فيها شخص ما بالتبرع على Ko-Fi!
هذا الموضوع عبارة عن ويكي. لا تتردد في تصحيح أي خطأ تراه ومناقشة كيفية تحسين هذا الدليل.
عنوان URL محدد، في هذا السياق. على سبيل المثال،
https://your-discourse.com/posts.json↩︎بعض المعلومات حول واجهة برمجة تطبيقاتهم: https://help.ko-fi.com/hc/en-us/articles/360004162298-Does-Ko-fi-Have-an-API-or-Webhook- ↩︎
يمكن العثور على معرف المنشور في كود HTML. إنه عنصر
<article>مع السمة التالية:data-post-id="POST_ID"↩︎
