Existen varias guías que cubren diversos usos o explicaciones de la API.
Esta ofrece ejemplos prácticos y completos sobre cómo utilizarla.
Todos los ejemplos de código en esta guía no pretenden mostrar buenas prácticas ni deben usarse tal cual.
Se omiten o saltan intencionalmente muchas comprobaciones, manejo de errores, etc., para centrarse exclusivamente en el uso de la API.
¿Para qué se utiliza la API?
La mayoría de tus acciones en Discourse (publicar, dar me gusta, editar una configuración, etc.) se realizan mediante la API haciendo peticiones a un endpoint[1].
Por ejemplo, cuando creas un tema en meta, se realiza una solicitud POST a https://meta.discourse.org/posts.json. La solicitud contiene, entre otras cosas, el autor, el título, la categoría, las etiquetas y el contenido de tu publicación.
El uso personalizado de la API suele realizarse para automatizar tareas y a menudo en combinación con otros servicios, como webhooks, scripts, software de terceros y APIs.
Para utilizar la API, es obligatorio tener credenciales de API. Esto se puede hacer en pocos clics siguiendo esta guía: Create and configure an API key
No esperes más y vamos con un primer ejemplo de un caso de uso de la API. 
Crear un tema mensual
En este ejemplo, utilizaremos curl y cron para crear un tema mensual de “charla libre” en tu foro. Una práctica popular en las comunidades en línea 
Crear la clave de API
Sigue la guía de creación de claves de API. Establece el Nivel de usuario en Usuario único.
El usuario elegido será el autor del tema mensual.
Luego puedes optar por un ámbito Global o un ámbito Granular, en cuyo caso deberá tener al menos el acceso de Tópicos → Escribir.
Anota tu clave de API generada. 
Crear un comando curl
Desde la línea de comandos de tu servidor, ejecuta este comando para ver si funciona y si se crea correctamente un tema utilizando curl y la API REST de Discourse con tu clave de API:
curl -X POST "https://tu-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: TU_CLAVE_API" -H "Api-Username: TU_USUARIO" -d "{\"title\": \"Prueba de creación de tema con la API\", \"raw\": \"Y aquí está el contenido del tema\", \"category\": ID_CATEGORIA }"
Reemplaza:
tu-discourse.comcon el dominio de tu foroTU_CLAVE_APIcon tu clave de APITU_USUARIOcon el nombre de usuario elegido para la clave de APIID_CATEGORIAcon el ID de la categoría en la que quieres publicar tu tema.
Si todo está configurado correctamente, se debería crear un nuevo tema de prueba en tu foro, como:
¡La mayor parte del trabajo está hecho en esta etapa! Ahora necesitamos cambiar el título y el contenido del tema por algo más apropiado y configurar la recurrencia de la creación del tema.
Comienza cambiando el título del tema de:
Prueba de creación de tema con la API
a:
Charla libre del mes - $(date +\%B).
Hagamos lo mismo para el contenido, cambiándolo de:
Prueba de creación de tema con la API
a:
¿Qué has apreciado más y menos durante $(date +\%B -d 'mes pasado')?\nSiéntete libre de compartir tus sentimientos y aportar ideas. 🙂
Estoy utilizando el comando Unix date para insertar el nombre del mes actual en el título y el nombre del mes anterior en el contenido.
\n en el contenido crea una nueva línea.
Puedes usar la línea de comandos y ejecutar la solicitud curl actualizada. Debería haber creado un nuevo tema en tu foro como este:
Configurar el evento recurrente
Crearemos una tarea cron que ejecute el comando curl el primer día de cada mes. 
Edita el archivo cron con el siguiente comando:
crontab -e
Inserta esta línea al final del archivo (reemplaza el contenido de la solicitud según sea necesario) y guarda la modificación.
0 0 1 * * curl -X POST "https://tu-discourse.com/posts.json" -H "Content-Type: application/json" -H "Api-Key: TU_CLAVE_API" -H "Api-Username: TU_USUARIO" -d "{\"title\": \"Charla libre del mes - $(date +\%B)\", \"raw\": \"¿Qué has apreciado más y menos durante $(date +\%B -d 'mes pasado')?\nSiéntete libre de compartir tus sentimientos y aportar ideas. 🙂\", \"category\": 4 }"
La parte 0 0 1 * * define el intervalo en el que se ejecutará el comando. Puedes aprender más sobre la sintaxis aquí: https://crontab.guru
¡Hecho! Tu servidor ahora creará un nuevo tema de “charla libre” el primer día de cada mes, utilizando la API REST de Discourse, una solicitud curl y una tarea cron. 
Cambiar automáticamente el esquema de color de un tema
Hagamos que nuestro tema predeterminado utilice un esquema de color que coincida con la estación actual 
Utilizaremos Ruby para manejar las comprobaciones de los meses y una tarea cron para ejecutar el script.
Podríamos usar muchas otras formas distintas de Ruby y cron, pero esta guía también pretende mostrar cómo usar la API con diversas herramientas.
Preparar el tema y los esquemas de color
Elige el tema al que quieres cambiar el esquema de color y obtén su ID. Encontrarás el ID en la URL del tema. Por ejemplo, el ID de este tema es 1:
Crea 4 paletas de colores y anota sus IDs también.
Aquí, el ID de la paleta de otoño es 17:
Crear el script
Instala Ruby en tu servidor.
Crea un archivo seasons.rb. Consideraré que está en ~/scripts/ para este ejemplo.
Pon el siguiente contenido en este archivo. Realizaremos una solicitud PUT a nuestro endpoint de temas y enviaremos un payload que contenga el ID del esquema de color:
require 'net/http'
require 'json'
require 'date'
current_month = Date.today.month
color_scheme_id = case current_month
when 1..3 then 18 # Invierno
when 4..6 then 15 # Primavera
when 7..9 then 16 # Verano
else 17 # Otoño
end
uri = URI('https://tu-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' => 'TU_CLAVE_API',
'Api-Username' => 'TU_USUARIO',
'Content-Type' => 'application/json'
})
request.body = JSON.generate({
"theme" => {
"color_scheme_id" => color_scheme_id
}
})
response = http.request(request)
Reemplaza:
tu-discourse.comcon el dominio de tu foroTU_CLAVE_APIcon tu clave de APITU_USUARIOcon el nombre de usuario elegido para la clave de APIID_TEMAcon el ID de tu tema. Puedes encontrarlo al final de la URL de la página de configuración del tema.
Por ejemplo, enhttps://tu-discourse.com/admin/customize/themes/38, el ID del tema es38.
Probemos manualmente tu script.
Primero, configúralo en un esquema de color no estacional en la interfaz de Discourse si aún no lo está.
Luego, ejecuta el script con el siguiente comando:
ruby ~/scripts/seasons.rb
Actualiza tu navegador. El esquema de color utilizado por tu tema debería haber cambiado.
Lo último que queda por hacer es crear la tarea cron que ejecutará este script el primer día del mes en cada cambio de estación.
Vuelve a ver el primer ejemplo si no recuerdas cómo crear una tarea cron.
0 0 1 1,4,7,10 * ruby ~/scripts/seasons.rb
¡Hecho! Tu foro ahora lucirá nuevos colores al comienzo de cada nueva estación.
Recibir una solicitud web en un servidor web y usar sus datos para actualizar un tema de Discourse
¡Este es más complejo!
Nuestra herramienta será PHP, lo que significa que asumiremos que tienes un servidor web funcional en algún lugar con PHP instalado.
En este ejemplo, recibiremos una carga útil de webhook de Ko-Fi (un servicio de donaciones) en una página PHP, que luego utilizará los datos recibidos para usar la API de Discourse y actualizar el título y el contenido de un tema.
Más específicamente, actualizará el título del tema con el monto y la fecha de la donación, y añadirá una nueva línea a la tabla que lista las donaciones anteriores (¡incluso hará subir automáticamente el tema 
):
Cada vez que un usuario hace una donación, Ko-Fi[2] enviará una solicitud a nuestro script PHP.
Configurar Ko-Fi
Configuré la configuración en la página de webhooks de Ko-Fi simplemente añadiendo la URL de mi archivo PHP y anotando el token de verificación oculto en la sección Avanzado.
En una donación individual, Ko-Fi enviará una carga útil como esta a nuestro 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 Ejemplo",
"message": "¡Buena suerte con la integración!",
"amount": "3.00",
"url": "https://ko-fi.com/Home/CoffeeShop?txid=00000000-1111-2222-3333-444444444444",
"email": "jo.ejemplo@ejemplo.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
}
Recibiremos esta carga útil y luego extraeremos la información que necesitamos:
-
El monto (
3.00), que redondearemos a un número entero. -
El timestamp (
2023-10-19T13:35:06Z), que formatearemos en una fecha más legible.
Recibir la carga útil de Ko-Fi
Primero, ponemos el siguiente código en nuestra página PHP para recibir la solicitud de Ko-Fi, donde nos aseguramos de que hemos recibido una solicitud POST y que el valor del token coincide con el proporcionado en la página de webhooks de Ko-Fi. También formateamos el monto y la fecha como se mencionó anteriormente.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'TU_TOKEN_VERIFICACION') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
}
}
Reemplaza:
TU_TOKEN_VERIFICACIONcon el token proporcionado por Ko-Fi
Actualizar el título del tema
El siguiente paso es actualizar el título de nuestro tema. Utilizaremos curl en nuestro script PHP para realizar una solicitud PUT al endpoint adecuado.
$putData = json_encode(['title' => '🥳 Nueva donación: ' . $amount . '€ el ' . $date]);
$ch = curl_init('https://tu-discourse.com/t/prueba-nuevo-tema/ID_TEMA');
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: TU_CLAVE_API',
'Api-Username: TU_USUARIO'
]);
curl_exec($ch);
Reemplaza:
tu-discourse.comcon el dominio de tu foroID_TEMAcon el ID correcto del temaTU_CLAVE_APIcon tu clave de APITU_USUARIOcon el nombre de usuario elegido para la clave de API
Actualizar el contenido de la publicación
Para poder agregar nuevo contenido a la primera publicación del tema, primero necesitamos recuperar su contenido actual con una solicitud GET.
$ch_get = curl_init('https://tu-discourse.com/posts/ID_PUBLICACION.json');
curl_setopt($ch_get, CURLOPT_RETURNTRANSFER, true);
$currentContent = json_decode(curl_exec($ch_get), true)['raw'];
Reemplaza:
ID_PUBLICACIONcon el ID correcto de la publicación[3]
Finalmente, necesitamos actualizar el contenido de la publicación agregando una nueva línea a la tabla con el monto y la fecha. Lo haremos con una solicitud PUT.
$updatedContent = $currentContent . "\n| " . $amount . "€ | " . $date . " |";
$putPostData = json_encode(['post' => ['raw' => $updatedContent]]);
$ch_put = curl_init('https://tu-discourse.com/posts/ID_PUBLICACION');
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: TU_CLAVE_API',
'Api-Username: TU_USUARIO'
]);
curl_exec($ch_put);
Reemplaza:
tu-discourse.comcon el dominio de tu foroID_PUBLICACIONcon el ID correcto de la publicaciónTU_CLAVE_APIcon tu clave de APITU_USUARIOcon el nombre de usuario elegido para la clave de API
El código final se ve así:
<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$jsonData = json_decode($_POST['data'], true);
if ($jsonData['verification_token'] === 'TU_TOKEN_VERIFICACION') {
$amount = floor(floatval($jsonData['amount']));
$date = (new DateTime($jsonData['timestamp']))->format('d/m/Y');
$putData = json_encode(['title' => '🥳 Nueva donación: ' . $amount . '€ el ' . $date]);
$ch = curl_init('https://tu-discourse.com/t/prueba-nuevo-tema/ID_TEMA');
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: TU_CLAVE_API',
'Api-Username: TU_USUARIO'
]);
curl_exec($ch);
$ch_get = curl_init('https://tu-discourse.com/posts/ID_PUBLICACION.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://tu-discourse.com/posts/ID_PUBLICACION');
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: TU_CLAVE_API',
'Api-Username: TU_USUARIO'
]);
curl_exec($ch_put);
curl_close($ch);
curl_close($ch_get);
curl_close($ch_put);
} else {
http_response_code(403);
echo "Token de verificación inválido.";
}
} else {
http_response_code(405);
echo "Solo se permiten solicitudes POST.";
}
?>
Déjame enfatizar nuevamente la advertencia al principio de esta guía 
Se omiten o saltan intencionalmente muchas comprobaciones, manejo de errores, etc., para centrarse exclusivamente en el uso de la API.
Ahora podemos desencadenar una solicitud de prueba desde Ko-Fi y ver cómo actualiza nuestro tema, tanto el título como el contenido.
¡Eso es todo!
¡Tienes un tema que se actualizará y hará subir cada vez que alguien haga una donación en Ko-Fi!
Este tema es un wiki. Siéntete libre de corregir cualquier error que veas y de discutir cómo se podría mejorar esta guía.
Una URL específica, en este contexto. Por ejemplo,
https://tu-discourse.com/posts.json↩︎Un poco de información sobre su API: https://help.ko-fi.com/hc/en-us/articles/360004162298-Does-Ko-fi-Have-an-API-or-Webhook- ↩︎
El ID de la publicación se puede encontrar en el código HTML. Es un elemento
<article>con el siguiente atributo:data-post-id="ID_PUBLICACION"↩︎
