Il existe plusieurs guides couvrant divers usages ou explications de l’API.
Celui-ci fournit des exemples pratiques et complets sur la façon de l’utiliser.
Tous les exemples de code dans ce guide ne visent pas à présenter les bonnes pratiques ni à être utilisés tels quels.
Beaucoup de vérifications, de gestion d’erreurs, etc. sont volontairement ignorées ou omises pour se concentrer uniquement sur l’utilisation de l’API.
À quoi sert l’API ?
La plupart de vos actions sur Discourse (publication, like, modification d’un paramètre, etc.) sont effectuées via l’API en envoyant des requêtes vers un endpoint[1].
Par exemple, lorsque vous créez un sujet sur meta, une requête POST est envoyée vers https://meta.discourse.org/posts.json. La requête contient, entre autres, l’auteur, le titre, la catégorie, les tags et le contenu de votre message.
L’utilisation personnalisée de l’API est généralement réalisée pour automatiser des tâches et souvent en conjonction avec d’autres services, tels que les webhooks, des scripts, des logiciels tiers et d’autres API.
Pour utiliser l’API, il est obligatoire de posséder des identifiants API. Cela peut être fait en quelques clics en suivant ce guide : Create and configure an API key
N’attendez plus, passons à un premier exemple d’utilisation de l’API. 
Créer un sujet mensuel
Dans cet exemple, nous utiliserons curl et cron pour créer un sujet mensuel de “discussion libre” sur votre forum. Une pratique populaire dans les communautés en ligne 
Créer la clé API
Suivez le guide de création de clé API. Définissez le Niveau utilisateur sur Utilisateur unique.
L’utilisateur choisi sera l’auteur du sujet mensuel.
Ensuite, vous pouvez choisir une portée Globale ou Granulaire, dans ce cas, elle devra avoir au moins l’accès Sujets → Écrire.
Notez votre clé API générée. 
Créer une commande curl
Depuis la ligne de commande de votre serveur, exécutez cette commande pour vérifier si cela fonctionne et si un sujet est correctement créé en utilisant curl et l’API REST de Discourse avec votre clé API :
curl -X POST "https://votre-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: VOTRE_CLE_API" -H "Api-Username: VOTRE_NOM_UTILISATEUR" -d "{\"title\": \"Test de création de sujet avec l'API\", \"raw\": \"Et voici le contenu du sujet\", \"category\": ID_CATEGORIE }"
Remplacez :
votre-discourse.compar le domaine de votre forumVOTRE_CLE_APIpar votre clé APIVOTRE_NOM_UTILISATEURpar le nom d’utilisateur choisi pour la clé APIID_CATEGORIEpar l’ID de la catégorie dans laquelle vous souhaitez publier votre sujet.
Si tout est correctement configuré, un nouveau sujet de test devrait être créé sur votre forum, comme ceci :
La majeure partie du travail est faite à cette étape ! Nous devons maintenant changer le titre et le contenu du sujet pour quelque chose de plus approprié et configurer la récurrence de la création du sujet.
Commencez par changer le titre du sujet de :
Test de création de sujet avec l'API
en :
Discussion libre du mois - $(date +\%B).
Faisons de même pour le contenu, en passant de :
Test de création de sujet avec l'API
à :
Qu'avez-vous le plus et le moins apprécié au cours de $(date +\%B -d 'last month') ?\nN'hésitez pas à partager vos impressions et à proposer des idées. 🙂
J’utilise la commande Unix date pour insérer le nom du mois en cours dans le titre et le nom du mois précédent dans le contenu.
\n dans le contenu crée une nouvelle ligne.
Vous pouvez utiliser la ligne de commande et exécuter la requête curl mise à jour. Elle devrait avoir créé un nouveau sujet comme ceci sur votre forum :
Configurer l’événement récurrent
Nous allons créer une tâche cron qui exécutera la commande curl le premier jour de chaque mois. 
Éditez le fichier cron avec la commande suivante :
crontab -e
Insérez cette ligne à la fin du fichier (remplacez le contenu de la requête si nécessaire) et enregistrez la modification.
0 0 1 * * curl -X POST "https://votre-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: VOTRE_CLE_API" -H "Api-Username: VOTRE_NOM_UTILISATEUR" -d "{\"title\": \"Discussion libre du mois - $(date +\%B)\", \"raw\": \"Qu'avez-vous le plus et le moins apprécié au cours de $(date +\%B -d 'last month') ?\nN'hésitez pas à partager vos impressions et à proposer des idées. 🙂\", \"category\": 4 }"
La partie 0 0 1 * * définit l’intervalle auquel la commande sera exécutée. Vous pouvez en savoir plus sur la syntaxe ici : https://crontab.guru
C’est fait ! Votre serveur créera maintenant un nouveau sujet de “discussion libre” le premier jour de chaque mois, en utilisant l’API REST de Discourse, une requête curl et une tâche cron. 
Changer automatiquement le schéma de couleurs d’un thème
Faisons en sorte que notre thème par défaut utilise un schéma de couleurs correspondant à la saison actuelle 
Nous utiliserons Ruby pour gérer les vérifications des mois et une tâche cron pour exécuter le script.
Nous pourrions utiliser bien d’autres méthodes que Ruby et cron, mais ce guide vise également à montrer comment utiliser l’API avec divers outils.
Préparer le thème et les schémas de couleurs
Choisissez le thème dont vous souhaitez changer le schéma de couleurs et récupérez son ID. Vous trouverez l’ID dans l’URL du thème. Par exemple, l’ID de ce thème est 1 :
Créez 4 palettes de couleurs et notez également leurs ID.
Ici, l’ID de la palette d’automne est 17 :
Créer le script
Installez Ruby sur votre serveur.
Créez un fichier seasons.rb. Pour cet exemple, je considérerai qu’il se trouve dans ~/scripts/.
Mettez le contenu suivant dans ce fichier. Nous ferons une requête PUT vers notre endpoint de thème et enverrons un payload contenant l’ID du schéma de couleurs :
require 'net/http'
require 'json'
require 'date'
current_month = Date.today.month
color_scheme_id = case current_month
when 1..3 then 18 # Hiver
when 4..6 then 15 # Printemps
when 7..9 then 16 # Été
else 17 # Automne
end
uri = URI('https://votre-discourse.com/admin/themes/ID_THEME.json')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, {
'Api-Key' => 'VOTRE_CLE_API',
'Api-Username' => 'VOTRE_NOM_UTILISATEUR',
'Content-Type' => 'application/json'
})
request.body = JSON.generate({
"theme" => {
"color_scheme_id" => color_scheme_id
}
})
response = http.request(request)
Remplacez :
votre-discourse.compar le domaine de votre forumVOTRE_CLE_APIpar votre clé APIVOTRE_NOM_UTILISATEURpar le nom d’utilisateur choisi pour la clé APIID_THEMEpar l’ID de votre thème. Vous pouvez le trouver à la fin de l’URL de la page de paramètres du thème.
Par exemple, danshttps://votre-discourse.com/admin/customize/themes/38, l’ID du thème est38.
Essayons manuellement votre script.
D’abord, définissez-le sur un schéma de couleurs non saisonnier dans l’interface de Discourse si ce n’est pas déjà le cas.
Ensuite, exécutez le script avec la commande suivante :
ruby ~/scripts/seasons.rb
Actualisez votre navigateur. Le schéma de couleurs utilisé par votre thème devrait avoir changé.
La dernière chose à faire est de créer la tâche cron qui exécutera ce script le premier jour du mois à chaque changement de saison.
Reportez-vous à le premier exemple si vous ne vous souvenez pas comment créer une tâche cron.
0 0 1 1,4,7,10 * ruby ~/scripts/seasons.rb
C’est fait ! Votre forum portera maintenant de nouvelles couleurs au début de chaque nouvelle saison !
Recevoir une requête web sur un serveur web et utiliser ses données pour mettre à jour un sujet Discourse
Celui-ci est plus complexe !
Notre outil sera PHP, ce qui signifie que nous supposerons que vous avez un serveur web fonctionnel quelque part avec PHP installé.
Dans cet exemple, nous recevrons une charge utile de webhook Ko-Fi (un service de dons) sur une page PHP, qui utilisera ensuite les données reçues pour utiliser l’API de Discourse et mettre à jour le titre et le contenu d’un sujet.
Plus précisément, elle mettra à jour le titre du sujet avec le montant du don et la date, et ajoutera une nouvelle ligne au tableau listant les dons précédents (elle fera même remonter automatiquement le sujet 
) :
À chaque fois qu’un utilisateur fait un don, Ko-Fi[2] enverra une requête à notre script PHP.
Configurer Ko-Fi
J’ai configuré la configuration sur la page des webhooks de Ko-Fi en ajoutant simplement l’URL de mon fichier PHP et en notant le token de vérification caché dans la section Avancée.
Pour un don unique, Ko-Fi enverra une charge utile comme celle-ci à notre script 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": "Bonne chance pour l'intégration !",
"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
}
Nous recevrons cette charge utile, puis extrairons les deux informations dont nous avons besoin :
-
Le montant (
3.00), que nous arrondirons à un entier. -
L’horodatage (
2023-10-19T13:35:06Z), que nous formaterons en une date plus jolie.
Recevoir la charge utile de Ko-Fi
D’abord, nous mettons le code suivant dans notre page PHP pour recevoir la requête de Ko-Fi, où nous nous assurons d’avoir reçu une requête POST et que la valeur du token correspond à celle donnée sur la page des webhooks de Ko-Fi. Nous formatons également le montant et la date comme indiqué précédemment.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'VOTRE_TOKEN_VERIFICATION') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
}
}
Remplacez :
VOTRE_TOKEN_VERIFICATIONpar le token fourni par Ko-Fi
Mettre à jour le titre du sujet
L’étape suivante consiste à mettre à jour le titre de notre sujet. Nous utiliserons curl dans notre script PHP pour effectuer une requête PUT vers le bon endpoint.
$putData = json_encode(['title' => '🥳 Nouveau don : ' . $amount . '€ le ' . $date]);
$ch = curl_init('https://votre-discourse.com/t/test-nouveau-sujet/ID_SUJET');
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: VOTRE_CLE_API',
'Api-Username: VOTRE_NOM_UTILISATEUR'
]);
curl_exec($ch);
Remplacez :
votre-discourse.compar le domaine de votre forumID_SUJETpar l’ID correct du sujetVOTRE_CLE_APIpar votre clé APIVOTRE_NOM_UTILISATEURpar le nom d’utilisateur choisi pour la clé API
Mettre à jour le contenu du message
Pour pouvoir ajouter du nouveau contenu au premier message du sujet, nous devons d’abord récupérer son contenu actuel avec une requête GET.
$ch_get = curl_init('https://votre-discourse.com/posts/ID_MESSAGE.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
Remplacez :
ID_MESSAGEpar l’ID correct du message[3]
Enfin, nous devons mettre à jour le contenu du message en ajoutant une nouvelle ligne au tableau avec le montant et la date. Nous ferons cela avec une requête PUT.
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://votre-discourse.com/posts/ID_MESSAGE');
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: VOTRE_CLE_API',
'Api-Username: VOTRE_NOM_UTILISATEUR'
]);
curl_exec($ch_put);
Remplacez :
votre-discourse.compar le domaine de votre forumID_MESSAGEpar l’ID correct du messageVOTRE_CLE_APIpar votre clé APIVOTRE_NOM_UTILISATEURpar le nom d’utilisateur choisi pour la clé API
Le code final ressemble à ceci :
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'VOTRE_TOKEN_VERIFICATION') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
$putData = json_encode(['title' => '🥳 Nouveau don : ' . $amount . '€ le ' . $date]);
$ch = curl_init('https://votre-discourse.com/t/test-nouveau-sujet/ID_SUJET');
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: VOTRE_CLE_API',
'Api-Username: VOTRE_NOM_UTILISATEUR'
]);
curl_exec($ch);
$ch_get = curl_init('https://votre-discourse.com/posts/ID_MESSAGE.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://votre-discourse.com/posts/ID_MESSAGE');
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: VOTRE_CLE_API',
'Api-Username: VOTRE_NOM_UTILISATEUR'
]);
curl_exec($ch_put);
curl_close($ch);
curl_close($ch_get);
curl_close($ch_put);
} else {
http_response_code(403);
echo "Token de vérification invalide.";
}
} else {
http_response_code(405);
echo "Seules les requêtes POST sont autorisées.";
}
?>
Je tiens à souligner à nouveau l’avertissement au début de ce guide 
Beaucoup de vérifications, de gestion d’erreurs, etc. sont volontairement ignorées ou omises pour se concentrer uniquement sur l’utilisation de l’API.
Nous pouvons maintenant déclencher une requête de test depuis Ko-Fi et voir comment elle met à jour notre sujet, tant le titre que le contenu.
C’est tout !
Vous avez maintenant un sujet qui sera mis à jour et remonté à chaque fois que quelqu’un fait un don sur Ko-Fi !
Ce sujet est un wiki. N’hésitez pas à corriger toute erreur que vous voyez et à discuter de la façon dont ce guide pourrait être amélioré.
Une URL spécifique, dans ce contexte. Par exemple,
https://votre-discourse.com/posts.json↩︎Un peu d’infos sur leur API : https://help.ko-fi.com/hc/en-us/articles/360004162298-Does-Ko-fi-Have-an-API-or-Webhook- ↩︎
L’ID du message peut être trouvé dans le code HTML. C’est un élément
<article>avec l’attribut suivant :data-post-id="ID_MESSAGE"↩︎
