Es gibt mehrere Anleitungen, die verschiedene API-Anwendungen oder -Erklärungen abdecken.
Diese hier liefert praktische und umfassende Beispiele dafür, wie man sie nutzt.
Alle Code-Beispiele in dieser Anleitung sollen keine bewährten Praktiken darstellen oder so, wie sie sind, verwendet werden.
Viele Prüfungen, Fehlerbehandlungen und Ähnliches werden absichtlich ignoriert oder übersprungen, um sich rein auf die Nutzung der API zu konzentrieren.
Wofür wird die API verwendet?
Die meisten deiner Aktionen in Discourse (Beiträge verfassen, liken, eine Einstellung bearbeiten usw.) werden über die API ausgeführt, indem Anfragen an einen Endpunkt[1] gesendet werden.
Wenn du beispielsweise auf Meta ein Thema erstellst, wird eine POST-Anfrage an https://meta.discourse.org/posts.json gesendet. Die Anfrage enthält unter anderem den Autor, den Titel, die Kategorie, die Tags und den Inhalt deines Beitrags.
Die benutzerdefinierte Nutzung der API dient in der Regel der Automatisierung von Aufgaben und erfolgt oft in Kombination mit anderen Diensten wie Webhooks, Skripten, Software von Drittanbietern und APIs.
Um die API zu nutzen, sind API-Anmeldedaten erforderlich. Dies lässt sich mit wenigen Klicks erledigen, indem du dieser Anleitung folgst: Create and configure an API key
Warte nicht länger, lass uns mit einem ersten Beispiel für einen API-Einsatzfall starten. 
Ein monatliches Thema erstellen
In diesem Beispiel verwenden wir curl und cron, um auf deinem Forum ein monatliches „Freitalk“-Thema zu erstellen. Eine beliebte Praxis in Online-Communities 
API-Schlüssel erstellen
Folge der Anleitung zum Erstellen eines API-Schlüssels. Setze die Benutzerebene auf „Einzelner Benutzer“.
Der ausgewählte Benutzer wird der Autor des monatlichen Themas sein.
Anschließend kannst du entweder den Global-Bereich oder den Granular-Bereich wählen. Im letzteren Fall muss mindestens der Zugriff Themen → Schreiben vorhanden sein.
Schreibe deinen generierten API-Schlüssel auf. 
Eine curl-Befehlszeile erstellen
Führe auf der Kommandozeile deines Servers folgenden Befehl aus, um zu prüfen, ob er funktioniert und ob ein Thema ordnungsgemäß mit curl und der REST-API von Discourse unter Verwendung deines API-Schlüssels erstellt wird:
curl -X POST "https://dein-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: DEIN_API_SCHLUESSEL" -H "Api-Username: DEIN_BENUTZERNAME" -d "{\"title\": \"Test-Thema-Erstellung mit der API\", \"raw\": \"Und hier ist der Inhalt des Themas\", \"category\": KATEGORIE_ID }"
Ersetze:
dein-discourse.comdurch die Domain deines ForumsDEIN_API_SCHLUESSELdurch deinen API-SchlüsselDEIN_BENUTZERNAMEdurch den Benutzernamen, der für den API-Schlüssel ausgewählt wurdeKATEGORIE_IDdurch die ID der Kategorie, in der du dein Thema veröffentlichen möchtest.
Wenn alles ordnungsgemäß konfiguriert ist, sollte auf deinem Forum ein neues Test-Thema erstellt werden, wie zum Beispiel:
Der Großteil der Arbeit ist in diesem Stadium erledigt! Jetzt müssen wir den Titel und den Inhalt des Themas für etwas Passenderes ändern und die Wiederholung der Themenerstellung einrichten.
Beginne damit, den Titel des Themas von:
Test-Thema-Erstellung mit der API
in:
Freitalk des Monats - $(date +\%B)
zu ändern.
Machen wir dasselbe für den Inhalt von:
Test-Thema-Erstellung mit der API
in:
Was hast du im vergangenen $(date +\%B -d 'last month') am meisten und am wenigsten geschätzt?\nFühle dich frei, deine Gefühle zu teilen und Ideen beizusteuern. 🙂
Ich verwende den Unix-Befehl date, um den Namen des aktuellen Monats im Titel und den Namen des vorherigen Monats im Inhalt einzufügen.
\n im Inhalt erstellt eine neue Zeile.
Du kannst die Kommandozeile verwenden und die aktualisierte curl-Anfrage ausführen. Sie sollte auf deinem Forum ein neues Thema wie dieses erstellt haben:
Das wiederkehrende Ereignis einrichten
Wir erstellen eine cron-Aufgabe, die den curl-Befehl am ersten Tag jedes Monats ausführt. 
Bearbeite die cron-Datei mit folgendem Befehl:
crontab -e
Füge diese Zeile am Ende der Datei ein (ersetze den Inhalt der Anfrage nach Bedarf) und speichere die Änderung.
0 0 1 * * curl -X POST "https://dein-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: DEIN_API_SCHLUESSEL" -H "Api-Username: DEIN_BENUTZERNAME" -d "{\"title\": \"Freitalk des Monats - $(date +\%B)\", \"raw\": \"Was hast du im vergangenen $(date +\%B -d 'last month') am meisten und am wenigsten geschätzt?\nFühle dich frei, deine Gefühle zu teilen und Ideen beizusteuern. 🙂\", \"category\": 4 }"
Der Teil 0 0 1 * * definiert das Intervall, in dem der Befehl ausgeführt wird. Mehr zur Syntax erfährst du hier: https://crontab.guru
Es ist erledigt! Dein Server erstellt nun am ersten Tag jedes Monats ein neues „Freitalk“-Thema, und zwar mit der REST-API von Discourse, einer curl-Anfrage und einer cron-Aufgabe. 
Automatisch das Farbschema eines Themas ändern
Lass uns unser Standardthema so konfigurieren, dass es ein Farbschema verwendet, das zur aktuellen Jahreszeit passt 
Wir verwenden Ruby, um die Monatsprüfungen durchzuführen, und eine cron-Aufgabe, um das Skript auszuführen.
Wir könnten viele andere Wege als Ruby und cron wählen, aber diese Anleitung zielt auch darauf ab, zu zeigen, wie man die API mit verschiedenen Tools nutzt.
Das Thema und die Farbschemata vorbereiten
Wähle das Thema aus, dessen Farbschema du ändern möchtest, und notiere dir dessen ID. Die ID findest du in der URL des Themas. Zum Beispiel ist die ID dieses Themas 1:
Erstelle 4 Farbpaletten und notiere dir auch deren IDs.
Hier ist die ID der Herbst-Palette 17:
Das Skript erstellen
Installiere Ruby auf deinem Server.
Erstelle eine Datei namens seasons.rb. Für dieses Beispiel gehe ich davon aus, dass sie sich in ~/scripts/ befindet.
Füge den folgenden Inhalt in diese Datei ein. Wir senden eine PUT-Anfrage an unseren Theme-Endpunkt und übermitteln eine Nutzlast, die die ID des Farbschemas enthält:
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 # Frühling
when 7..9 then 16 # Sommer
else 17 # Herbst
end
uri = URI('https://dein-discourse.com/admin/themes/THEMA_ID.json')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, {
'Api-Key' => 'DEIN_API_SCHLUESSEL',
'Api-Username' => 'DEIN_BENUTZERNAME',
'Content-Type' => 'application/json'
})
request.body = JSON.generate({
"theme" => {
"color_scheme_id" => color_scheme_id
}
})
response = http.request(request)
Ersetze:
dein-discourse.comdurch die Domain deines ForumsDEIN_API_SCHLUESSELdurch deinen API-SchlüsselDEIN_BENUTZERNAMEdurch den Benutzernamen, der für den API-Schlüssel ausgewählt wurdeTHEMA_IDdurch die ID deines Themas. Du findest sie am Ende der URL der Einstellungsseite des Themas.
Zum Beispiel: Beihttps://dein-discourse.com/admin/customize/themes/38ist die ID des Themas38.
Lass uns dein Skript manuell testen.
Stelle es zunächst in der Benutzeroberfläche von Discourse auf ein nicht jahreszeitabhängiges Farbschema um, falls dies noch nicht der Fall ist.
Führe dann das Skript mit folgendem Befehl aus:
ruby ~/scripts/seasons.rb
Aktualisiere deinen Browser. Das von deinem Thema verwendete Farbschema sollte sich geändert haben.
Das Letzte, was zu tun ist, besteht darin, die cron-Aufgabe zu erstellen, die dieses Skript am ersten Tag des Monats bei jedem Wechsel der Jahreszeit ausführt.
Schau dir das erste Beispiel noch einmal an, falls du nicht mehr weißt, wie man eine cron-Aufgabe erstellt.
0 0 1 1,4,7,10 * ruby ~/scripts/seasons.rb
Es ist erledigt! Dein Forum wird nun zu Beginn jeder neuen Jahreszeit neue Farben tragen!
Eine Webanfrage auf einem Webserver empfangen und deren Daten verwenden, um ein Discourse-Thema zu aktualisieren
Dieser ist etwas komplexer!
Unser Werkzeug ist PHP, was bedeutet, dass wir davon ausgehen, dass du irgendwo einen funktionierenden Webserver mit installierter PHP-Umgebung hast.
In diesem Beispiel empfangen wir auf einer PHP-Seite eine Ko-Fi (ein Spendendienst) Webhook-Nutzlast, die dann die empfangenen Daten verwendet, um die API von Discourse aufzurufen und den Titel und den Inhalt eines Themas zu aktualisieren.
Genauer gesagt wird der Titel des Themas mit dem Spendenbetrag und dem Datum aktualisiert, und eine neue Zeile wird der Tabelle hinzugefügt, die frühere Spenden auflistet (es wird sogar automatisch das Thema nach oben holen 
):
Jedes Mal, wenn ein Benutzer eine Spende tätigt, sendet Ko-Fi[2] eine Anfrage an unser PHP-Skript.
Ko-Fi konfigurieren
Ich habe die Konfiguration auf der Ko-Fi-Webhook-Seite eingerichtet, indem ich einfach die URL meiner PHP-Datei hinzugefügt und den im Abschnitt „Erweitert“ versteckten Verifizierungstoken notiert habe.
Bei einer einzelnen Spende sendet Ko-Fi eine Nutzlast wie diese an unser PHP-Skript:
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
}
Wir empfangen diese Nutzlast und extrahieren dann die beiden benötigten Informationen:
-
Den Betrag (
3.00), den wir auf eine ganze Zahl runden. -
Den Zeitstempel (
2023-10-19T13:35:06Z), den wir in ein hübscheres Datum formatieren.
Die Nutzlast von Ko-Fi empfangen
Zuerst fügen wir den folgenden Code in unsere PHP-Seite ein, um die Anfrage von Ko-Fi zu empfangen. Dabei stellen wir sicher, dass wir eine POST-Anfrage erhalten haben und dass der Token-Wert mit dem auf der Ko-Fi-Webhook-Seite angegebenen übereinstimmt. Wir formatieren auch den Betrag und das Datum wie zuvor erwähnt.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'DEIN_VERIFIZIERUNGSTOKEN') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
}
}
Ersetze:
DEIN_VERIFIZIERUNGSTOKENdurch den von Ko-Fi bereitgestellten Token
Den Titel des Themas aktualisieren
Der nächste Schritt besteht darin, den Titel unseres Themas zu aktualisieren. Wir verwenden curl in unserem PHP-Skript, um eine PUT-Anfrage an den entsprechenden Endpunkt zu senden.
$putData = json_encode(['title' => '🥳 Neue Spende: ' . $amount . '€ am ' . $date]);
$ch = curl_init('https://dein-discourse.com/t/test-neues-thema/THEMA_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: DEIN_API_SCHLUESSEL',
'Api-Username: DEIN_BENUTZERNAME'
]);
curl_exec($ch);
Ersetze:
dein-discourse.comdurch die Domain deines ForumsTHEMA_IDdurch die richtige ID des ThemasDEIN_API_SCHLUESSELdurch deinen API-SchlüsselDEIN_BENUTZERNAMEdurch den Benutzernamen, der für den API-Schlüssel ausgewählt wurde
Den Inhalt des Beitrags aktualisieren
Um neuen Inhalt zum ersten Beitrag des Themas hinzufügen zu können, müssen wir zunächst seinen aktuellen Inhalt mit einer GET-Anfrage abrufen.
$ch_get = curl_init('https://dein-discourse.com/posts/BEITRAG_ID.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
Ersetze:
BEITRAG_IDdurch die richtige ID des Beitrags[3]
Schließlich müssen wir den Beitrag-Inhalt aktualisieren, indem wir eine neue Zeile zur Tabelle mit Betrag und Datum hinzufügen. Dies erledigen wir mit einer PUT-Anfrage.
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://dein-discourse.com/posts/BEITRAG_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: DEIN_API_SCHLUESSEL',
'Api-Username: DEIN_BENUTZERNAME'
]);
curl_exec($ch_put);
Ersetze:
dein-discourse.comdurch die Domain deines ForumsBEITRAG_IDdurch die richtige ID des BeitragsDEIN_API_SCHLUESSELdurch deinen API-SchlüsselDEIN_BENUTZERNAMEdurch den Benutzernamen, der für den API-Schlüssel ausgewählt wurde
Der endgültige Code sieht so aus:
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'DEIN_VERIFIZIERUNGSTOKEN') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
$putData = json_encode(['title' => '🥳 Neue Spende: ' . $amount . '€ am ' . $date]);
$ch = curl_init('https://dein-discourse.com/t/test-neues-thema/THEMA_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: DEIN_API_SCHLUESSEL',
'Api-Username: DEIN_BENUTZERNAME'
]);
curl_exec($ch);
$ch_get = curl_init('https://dein-discourse.com/posts/BEITRAG_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://dein-discourse.com/posts/BEITRAG_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: DEIN_API_SCHLUESSEL',
'Api-Username: DEIN_BENUTZERNAME'
]);
curl_exec($ch_put);
curl_close($ch);
curl_close($ch_get);
curl_close($ch_put);
} else {
http_response_code(403);
echo "Ungültiger Verifizierungstoken.";
}
} else {
http_response_code(405);
echo "Nur POST-Anfragen sind erlaubt.";
}
?>
Ich möchte noch einmal auf die Warnung am Anfang dieser Anleitung hinweisen 
Viele Prüfungen, Fehlerbehandlungen und Ähnliches werden absichtlich ignoriert oder übersprungen, um sich rein auf die Nutzung der API zu konzentrieren.
Jetzt können wir eine Testanfrage von Ko-Fi auslösen und sehen, wie sie unser Thema aktualisiert, sowohl den Titel als auch den Inhalt.
Das war’s!
Du hast ein Thema, das jedes Mal aktualisiert und nach oben geholt wird, wenn jemand auf Ko-Fi eine Spende tätigt!
Dieses Thema ist ein Wiki. Bitte zögere nicht, alle Fehler zu korrigieren, die du siehst, und zu diskutieren, wie diese Anleitung verbessert werden kann.
Eine bestimmte URL, in diesem Kontext. Zum Beispiel:
https://dein-discourse.com/posts.json↩︎Ein paar Infos zu ihrer API: https://help.ko-fi.com/hc/en-us/articles/360004162298-Does-Ko-fi-Have-an-API-or-Webhook- ↩︎
Die Beitrags-ID findet man im HTML-Code. Es ist ein
<article>-Element mit dem folgenden Attribut:data-post-id="BEITRAG_ID"↩︎
