Mejorando la documentación de la API de Discourse para construir una comunidad frontend totalmente personalizada

Desarrollador
1

¡Hola a todos :waving_hand:

He estado desarrollando un frontend personalizado utilizando Discourse como backend headless (arquitectura basada en Next.js) y me gustaría compartir algunas brechas prácticas que he encontrado en el diseño actual de la API desde una perspectiva de integración del mundo real.

Esto no es una crítica a Discourse en sí mismo (es potente y flexible), sino más bien un feedback para mejorar la experiencia del desarrollador (DX) en arquitecturas modernas de frontend + impulsadas por API..

1. Paginación y estructura de publicaciones de temas

Problema actual:

  • La paginación no siempre es consistente en todos los endpoints

  • Las publicaciones de temas (/t/{id}.json) mezclan:

    • la publicación original

    • las respuestas

    • metadatos internos

  • Esto dificulta la construcción de un desplazamiento infinito limpio o un estado normalizado (Redux/Zustand/React Query)

Sugerencia:

  • Proporcionar una separación más clara o indicadores de consulta opcionales como:

    • ?include_first_post=true|false

    • ?posts_only=replies

    • Soporte para paginación basada en cursores (en lugar de solo basada en páginas)

2. Respuestas vs. Estructura de temas

Actualmente:

  • Las respuestas están incrustadas dentro de la respuesta del tema

  • No hay una separación clara entre:

    • “metadatos del tema”

    • “flujo de publicaciones”

Esto causa:

  • lógica de análisis adicional en el frontend

  • duplicación al normalizar el estado

Sugerencia:

  • Ofrecer endpoints dedicados como:

    • /t/{id}/posts

    • /t/{id}/replies

    • o soportar filtrado dentro de /t/{id}.json

3. Falta de documentación a nivel de campo en la respuesta de la API

Por ejemplo, en la respuesta del tema:

  • created_at

  • bumped_at

  • last_posted_at

  • updated_at

Estos no siempre están claramente diferenciados.

Problema:

  • Los desarrolladores a menudo interpretan mal:

    • bumped_at vs updated_at

    • qué desencadena la “actividad del tema”

Sugerencia:

  • Agregar documentación de esquema en línea o metadatos estilo OpenAPI:

    • significado de cada campo

    • explicación del ciclo de vida

4. Inconsistencias en estadísticas y caché

Problemas:

  • posts_count, reply_count, participants_count a veces se retrasan respecto a los datos en tiempo real

  • gran dependencia de contadores en caché

Impacto:

  • interfaz de usuario inexacta (especialmente para paneles / páginas de análisis)

  • requiere llamadas adicionales a la API para validar el estado

Sugerencia:

  • Agregar un indicador de “tiempo real vs. caché” o una variante de endpoint

  • O proporcionar actualizaciones basadas en webhooks/eventos para los conteos

5. Brechas en integración con Sitemap, SEO y frameworks

Al integrar con frameworks modernos (Next.js, Nuxt, etc.):

Problemas:

  • No hay una API unificada para:

    • temas actualizados para la generación de sitemaps

    • seguimiento de cambios a nivel de categoría

    • soporte completo de indexación de publicaciones

Los desarrolladores terminan haciendo:

  • múltiples llamadas a la API por categoría

  • comparación manual para updated_at

  • rastreo de paginación para detectar actualizaciones

Sugerencia:

  • Agregar endpoints dedicados:

    • /categories/updated

    • /topics/changes?since=timestamp

    • /sitemap.json (feed de sitemap impulsado por API)

6. Faltan métricas y agregaciones de usuarios

Datos comúnmente necesarios:

  • total de “me gusta” recibidos por usuario

  • total de “me gusta” dados

  • desglose de reacciones por publicación/usuario

  • estadísticas de participación por categoría

Problema actual:

  • requiere múltiples endpoints + agregación en el frontend

Sugerencia:

  • Agregar endpoints agregados como:

    • /users/{id}/stats

    • /topics/{id}/stats

7. Flexibilidad de avatares de usuario

Limitación actual:

  • los avatares están estrechamente acoplados con el sistema de carga de Discourse

Solicitud:

  • permitir URLs de avatares externos (S3 / CDN / proveedores de autenticación externos)

  • soportar:

    • external_avatar_url

Esto ayudaría con:

  • sistemas SSO

  • proveedores de identidad headless

8. Claves de API: Claves de administrador vs. Claves de usuario

Necesidad de aclaración en la documentación:

Diferencia entre:

  • clave de API de administrador

  • clave de API de usuario (creada vía /admin/api/keys o endpoints de API de usuario)

Preguntas:

  • reglas de ciclo de vida y expiración

  • reglas de revocación por usuario vs. globales

  • limitaciones de alcance de seguridad por tipo

Esto es crítico al construir integraciones de nivel de producción.

Reflexiones finales

La API de Discourse ya es poderosa, pero parece estar optimizada para “uso de foros renderizado en servidor” más que para “arquitectura headless / impulsada por frontend”.

Los frameworks modernos (Next.js, Remix, etc.) se benefician enormemente de:

  • menos idas y vueltas

  • límites de datos más claros

  • reglas de caché predecibles

  • mejores endpoints de agregación

Me encantaría recibir comentarios de los mantenedores u otros que estén construyendo configuraciones headless de Discourse.

Gracias :folded_hands:

2

Otra cosa que noté y que me molesta es que algunos endpoints están “protegidos” usando codificación de formularios en lugar de JSON, quizás para disuadir a las personas de manipular la API. El mejor ejemplo de esto es la API de seguimiento de clics en enlaces, lo cual tiene sentido como medida de protección, pero cualquiera todavía puede hacer un mal uso de ella si realmente lo desea. Al final del día, esto solo hace más difícil para los desarrolladores trabajar con la API.