Ci sono diverse guide che coprono vari utilizzi o spiegazioni dell’API.
Questa offre esempi pratici e completi su come utilizzarla.
Tutti gli esempi di codice in questa guida non sono intesi come best practice né vanno utilizzati così come sono.
Molti controlli, la gestione degli errori e altro sono volutamente ignorati o omessi per concentrarsi esclusivamente sull’uso dell’API.
A cosa serve l’API?
La maggior parte delle tue azioni su Discourse (pubblicare, mettere like, modificare una impostazione, ecc.) viene eseguita tramite l’API effettuando richieste a un endpoint[1].
Ad esempio, quando crei un argomento su meta, viene effettuata una richiesta POST a https://meta.discourse.org/posts.json. La richiesta contiene, tra le altre cose, l’autore, il titolo, la categoria, i tag e il contenuto del tuo post.
L’utilizzo personalizzato dell’API viene solitamente effettuato per automatizzare attività e spesso in combinazione con altri servizi, come webhook, script, software di terze parti e altre API.
Per utilizzare l’API è obbligatorio disporre di credenziali API. Questo può essere fatto in pochi clic, seguendo questa guida: Create and configure an API key
Non aspettare oltre, passiamo al primo esempio di utilizzo dell’API. 
Creare un argomento mensile
In questo esempio, useremo curl e cron per creare un argomento mensile “conversazione libera” sul tuo forum. Una pratica comune nelle comunità online 
Creare la chiave API
Segui la guida per la creazione della chiave API. Imposta Livello utente su Utente singolo.
L’utente scelto sarà l’autore dell’argomento mensile.
Successivamente, puoi scegliere un ambito Globale o un ambito Granulare; in quest’ultimo caso, dovrà avere almeno l’accesso Argomenti → Scrittura.
Annota la tua chiave API generata. 
Creare un comando curl
Dalla riga di comando del tuo server, esegui questo comando per verificare se funziona e se un argomento viene creato correttamente utilizzando curl e l’API REST di Discourse con la tua chiave API:
curl -X POST "https://il-tuo-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: LA_TUA_CHIAVE_API" -H "Api-Username: IL_TUO_NOME_UTENTE" -d "{\"title\": \"Creazione argomento di prova con l'API\", \"raw\": \"Ecco il contenuto dell'argomento\", \"category\": ID_CATEGORIA }"
Sostituisci:
il-tuo-discourse.comcon il dominio del tuo forumLA_TUA_CHIAVE_APIcon la tua chiave APIIL_TUO_NOME_UTENTEcon il nome utente scelto per la chiave APIID_CATEGORIAcon l’ID della categoria in cui vuoi pubblicare il tuo argomento.
Se tutto è configurato correttamente, sul tuo forum dovrebbe essere creato un nuovo argomento di prova, simile a questo:
La maggior parte del lavoro è fatta in questa fase! Ora dobbiamo modificare il titolo e il contenuto dell’argomento con qualcosa di più appropriato e impostare la ricorrenza della creazione dell’argomento.
Inizia modificando il titolo dell’argomento da:
Creazione argomento di prova con l'API
a:
Conversazione libera del mese - $(date +\%B).
Fai lo stesso per il contenuto, da:
Creazione argomento di prova con l'API
a:
Cosa hai apprezzato di più e di meno durante $(date +\%B -d 'last month')?\nSentiti libero di condividere i tuoi pensieri e fornire idee. 🙂
Sto usando il comando Unix date per inserire il nome del mese corrente nel titolo e quello del mese precedente nel contenuto.
\n nel contenuto crea una nuova riga.
Puoi usare la riga di comando ed eseguire la richiesta curl aggiornata. Dovrebbe aver creato un nuovo argomento sul tuo forum simile a questo:
Impostare l’evento ricorrente
Creeremo un’attività cron che eseguirà il comando curl il primo giorno di ogni mese. 
Modifica il file cron con il seguente comando:
crontab -e
Inserisci questa riga alla fine del file (modifica il contenuto della richiesta come necessario) e salva le modifiche.
0 0 1 * * curl -X POST "https://il-tuo-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: LA_TUA_CHIAVE_API" -H "Api-Username: IL_TUO_NOME_UTENTE" -d "{\"title\": \"Conversazione libera del mese - $(date +\%B)\", \"raw\": \"Cosa hai apprezzato di più e di meno durante $(date +\%B -d 'last month')?\nSentiti libero di condividere i tuoi pensieri e fornire idee. 🙂\", \"category\": 4 }"
La parte 0 0 1 * * definisce l’intervallo con cui verrà eseguita il comando. Puoi saperne di più sulla sintassi qui: https://crontab.guru
È fatto! Il tuo server creerà ora un nuovo argomento “conversazione libera” il primo giorno di ogni mese, utilizzando l’API REST di Discourse, una richiesta curl e un’attività cron. 
Cambiare automaticamente lo schema colori di un tema
Facciamo in modo che il nostro tema predefinito utilizzi uno schema colori che corrisponda alla stagione corrente 
Useremo Ruby per gestire i controlli sui mesi e un’attività cron per eseguire lo script.
Potremmo usare molti altri metodi oltre a Ruby e cron, ma questa guida mira anche a mostrare come utilizzare l’API con vari strumenti.
Preparare il tema e gli schemi colori
Scegli il tema a cui vuoi cambiare lo schema colori e ottieni il suo ID. Troverai l’ID nell’URL del tema. Ad esempio, l’ID di questo tema è 1:
Crea 4 palette colori e annota anche i loro ID.
Qui, l’ID della palette Autunnale è 17:
Creare lo script
Installa Ruby sul tuo server.
Crea un file seasons.rb. Per questo esempio, considererò che si trovi in ~/scripts/.
Inserisci il seguente contenuto in questo file. Effettueremo una richiesta PUT al nostro endpoint del tema e invieremo un payload contenente l’ID dello schema colori:
require 'net/http'
require 'json'
require 'date'
current_month = Date.today.month
color_scheme_id = case current_month
when 1..3 then 18 # Inverno
when 4..6 then 15 # Primavera
when 7..9 then 16 # Estate
else 17 # Autunno
end
uri = URI('https://il-tuo-discourse.com/admin/themes/ID_TEMA.json')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, {
'Api-Key' => 'LA_TUA_CHIAVE_API',
'Api-Username' => 'IL_TUO_NOME_UTENTE',
'Content-Type' => 'application/json'
})
request.body = JSON.generate({
"theme" => {
"color_scheme_id" => color_scheme_id
}
})
response = http.request(request)
Sostituisci:
il-tuo-discourse.comcon il dominio del tuo forumLA_TUA_CHIAVE_APIcon la tua chiave APIIL_TUO_NOME_UTENTEcon il nome utente scelto per la chiave APIID_TEMAcon l’ID del tuo tema. Puoi trovarlo alla fine dell’URL della pagina delle impostazioni del tema.
Ad esempio, inhttps://il-tuo-discourse.com/admin/customize/themes/38, l’ID del tema è38.
Proviamo manualmente lo script.
Prima, imposta uno schema colori non stagionale nell’interfaccia di Discourse, se non è già così.
Poi, esegui lo script con il seguente comando:
ruby ~/scripts/seasons.rb
Aggiorna il browser. Lo schema colori utilizzato dal tuo tema dovrebbe essere cambiato.
L’ultima cosa da fare è creare il job cron che eseguirà questo script il primo giorno del mese in corrispondenza di ogni cambio di stagione.
Dai un’occhiata al primo esempio se non ricordi come creare un’attività cron.
0 0 1 1,4,7,10 * ruby ~/scripts/seasons.rb
È fatto! Il tuo forum indosserà ora nuovi colori all’inizio di ogni nuova stagione!
Ricevere una richiesta web su un server web e utilizzare i suoi dati per aggiornare un argomento di Discourse
Questo è più complesso!
Il nostro strumento sarà PHP, il che significa che assumeremo di avere un server web funzionante da qualche parte con PHP installato.
In questo esempio, riceveremo un payload webhook di Ko-Fi (un servizio di donazioni) su una pagina PHP, che utilizzerà quindi i dati ricevuti per utilizzare l’API di Discourse e aggiornare il titolo e il contenuto di un argomento.
Più specificamente, aggiornerà il titolo dell’argomento con l’importo e la data della donazione, e aggiungerà una nuova riga alla tabella che elenca le donazioni precedenti (addirittura farà saltare automaticamente l’argomento 
):
Ogni volta che un utente effettua una donazione, Ko-Fi[2] invierà una richiesta al nostro script PHP.
Configurare Ko-Fi
Ho impostato la configurazione sulla pagina webhooks di Ko-Fi aggiungendo semplicemente l’URL del mio file PHP e annotando il token di verifica nascosto nella sezione Avanzate.
Su una singola donazione, Ko-Fi invierà un payload come questo al nostro 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": "Buona fortuna con l'integrazione!",
"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
}
Riceveremo questo payload, quindi estraiamo le due informazioni di cui abbiamo bisogno:
-
L’importo (
3.00), che arrotonderemo a un numero intero. -
L’timestamp (
2023-10-19T13:35:06Z), che formatteremo in una data più leggibile.
Ricevere il payload di Ko-Fi
Innanzitutto, mettiamo il seguente codice nella nostra pagina PHP per ricevere la richiesta da Ko-Fi, assicurandoci di aver ricevuto una richiesta POST e che il valore del token corrisponda a quello fornito nella pagina webhooks di Ko-Fi. Formattiamo anche l’importo e la data come detto prima.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'IL_TUO_TOKEN_DI_VERIFICA') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
}
}
Sostituisci:
IL_TUO_TOKEN_DI_VERIFICAcon il token fornito da Ko-Fi
Aggiornare il titolo dell’argomento
Il passaggio successivo è aggiornare il titolo del nostro argomento. Useremo curl nel nostro script PHP per effettuare una richiesta PUT al corretto endpoint.
$putData = json_encode(['title' => '🥳 Nuova donazione: ' . $amount . '€ il ' . $date]);
$ch = curl_init('https://il-tuo-discourse.com/t/test-nuovo-argomento/ID_ARGOMENTO');
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: LA_TUA_CHIAVE_API',
'Api-Username: IL_TUO_NOME_UTENTE'
]);
curl_exec($ch);
Sostituisci:
il-tuo-discourse.comcon il dominio del tuo forumID_ARGOMENTOcon l’ID corretto dell’argomentoLA_TUA_CHIAVE_APIcon la tua chiave APIIL_TUO_NOME_UTENTEcon il nome utente scelto per la chiave API
Aggiornare il contenuto del post
Per poter aggiungere nuovo contenuto al primo post dell’argomento, dobbiamo prima recuperarne il contenuto attuale con una richiesta GET.
$ch_get = curl_init('https://il-tuo-discourse.com/posts/ID_POST.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
Sostituisci:
ID_POSTcon l’ID corretto del post[3]
Infine, dobbiamo aggiornare il contenuto del post aggiungendo una nuova riga alla tabella con l’importo e la data. Lo faremo con una richiesta PUT.
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://il-tuo-discourse.com/posts/ID_POST');
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: LA_TUA_CHIAVE_API',
'Api-Username: IL_TUO_NOME_UTENTE'
]);
curl_exec($ch_put);
Sostituisci:
il-tuo-discourse.comcon il dominio del tuo forumID_POSTcon l’ID corretto del postLA_TUA_CHIAVE_APIcon la tua chiave APIIL_TUO_NOME_UTENTEcon il nome utente scelto per la chiave API
Il codice finale appare così:
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'IL_TUO_TOKEN_DI_VERIFICA') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
$putData = json_encode(['title' => '🥳 Nuova donazione: ' . $amount . '€ il ' . $date]);
$ch = curl_init('https://il-tuo-discourse.com/t/test-nuovo-argomento/ID_ARGOMENTO');
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: LA_TUA_CHIAVE_API',
'Api-Username: IL_TUO_NOME_UTENTE'
]);
curl_exec($ch);
$ch_get = curl_init('https://il-tuo-discourse.com/posts/ID_POST.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://il-tuo-discourse.com/posts/ID_POST');
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: LA_TUA_CHIAVE_API',
'Api-Username: IL_TUO_NOME_UTENTE'
]);
curl_exec($ch_put);
curl_close($ch);
curl_close($ch_get);
curl_close($ch_put);
} else {
http_response_code(403);
echo "Token di verifica non valido.";
}
} else {
http_response_code(405);
echo "Sono consentite solo richieste POST.";
}
?>
Ripeto ancora una volta l’avvertimento all’inizio di questa guida 
Molti controlli, la gestione degli errori e altro sono volutamente ignorati o omessi per concentrarsi esclusivamente sull’uso dell’API.
Ora possiamo attivare una richiesta di prova da Ko-Fi e vedere come aggiorna il nostro argomento, sia il titolo che il contenuto.
È tutto!
Hai un argomento che verrà aggiornato e fatto saltare ogni volta che qualcuno effettua una donazione su Ko-Fi!
Questo argomento è un wiki. Sentiti libero di correggere eventuali errori che vedi e di discutere su come migliorare questa guida.
Un URL specifico, in questo contesto. Ad esempio,
https://il-tuo-discourse.com/posts.json↩︎Un po’ di informazioni sulla loro API: https://help.ko-fi.com/hc/en-us/articles/360004162298-Does-Ko-fi-Have-an-API-or-Webhook- ↩︎
L’ID del post può essere trovato nel codice HTML. È un elemento
<article>con il seguente attributo:data-post-id="ID_POST"↩︎
