Migliorare la documentazione dell'API Discourse per creare una community frontend completamente personalizzata

Sviluppatore
1

Ciao a tutti :waving_hand:

Sto sviluppando un frontend personalizzato utilizzando Discourse come backend headless (architettura basata su Next.js) e vorrei condividere alcune lacune pratiche che ho riscontrato nella progettazione attuale dell’API, dal punto di vista di un’integrazione reale.

Non si tratta di una critica a Discourse in sé (che è potente e flessibile), ma piuttosto di un feedback per migliorare l’esperienza degli sviluppatori (DX) nelle moderne architetture frontend + API-driven..

1. Paginazione e Struttura dei Post nei Topic

Problema attuale:

  • La paginazione non è sempre coerente tra i vari endpoint

  • I post del topic (/t/{id}.json) mescolano:

    • il post originale

    • le risposte

    • i metadati interni

Questo rende piĂą difficile implementare uno scroll infinito pulito o uno stato normalizzato (Redux/Zustand/React Query)

Suggerimento:

  • Fornire una separazione piĂą chiara o flag di query opzionali come:

    • ?include_first_post=true|false

    • ?posts_only=replies

    • Supporto per la paginazione basata su cursori (invece che solo basata su pagine)

2. Risposte vs Struttura del Topic

Attualmente:

  • Le risposte sono incorporate nella risposta del topic

  • Non c’è una chiara separazione tra:

    • “metadati del topic”

    • “flusso di post”

Questo causa:

  • logica di parsing aggiuntiva nel frontend

  • duplicazione durante la normalizzazione dello stato

Suggerimento:

  • Offrire endpoint dedicati come:

    • /t/{id}/posts

    • /t/{id}/replies

    • oppure supportare il filtraggio all’interno di /t/{id}.json

3. Mancanza di Documentazione a Livello di Campo nella Risposta API

Ad esempio, nella risposta del topic:

  • created_at

  • bumped_at

  • last_posted_at

  • updated_at

Questi campi non sono sempre chiaramente differenziati.

Problema:

  • Gli sviluppatori spesso interpretano erroneamente:

    • bumped_at rispetto a updated_at

    • cosa attiva l’“attivitĂ  del topic”

Suggerimento:

  • Aggiungere documentazione dello schema inline o metadati in stile OpenAPI:

    • significato di ogni campo

    • spiegazione del ciclo di vita

4. Incoerenze nelle Statistiche e nella Cache

Problemi:

  • posts_count, reply_count, participants_count a volte sono in ritardo rispetto ai dati in tempo reale

  • forte affidamento su contatori in cache

Impatto:

  • interfaccia utente inaccurata (specialmente per dashboard / pagine di analisi)

  • necessitĂ  di chiamate API aggiuntive per validare lo stato

Suggerimento:

  • Aggiungere un indicatore “tempo reale vs cache” o una variante dell’endpoint

  • Oppure fornire aggiornamenti tramite webhook/eventi per i conteggi

5. Lacune nell’Integrazione con Sitemap, SEO e Framework

Quando si integra con framework moderni (Next.js, Nuxt, ecc.):

Problemi:

  • Nessun API unificato per:

    • topic aggiornati per la generazione della sitemap

    • tracciamento dell’ultima modifica a livello di categoria

    • supporto completo per l’indicizzazione dei post

Gli sviluppatori finiscono per dover fare:

  • multiple chiamate API per categoria

  • differenziazione manuale per updated_at

  • crawl della paginazione per rilevare aggiornamenti

Suggerimento:

  • Aggiungere endpoint dedicati:

    • /categories/updated

    • /topics/changes?since=timestamp

    • /sitemap.json (feed di sitemap guidato da API)

6. Metriche e Aggregazioni Utenti Mancanti

Dati comunemente necessari:

  • totali like ricevuti per utente

  • totali like inviati

  • dettaglio delle reazioni per post/utente

  • statistiche di engagement per categoria

Problema attuale:

  • richiede multiple endpoint + aggregazione sul frontend

Suggerimento:

  • Aggiungere endpoint aggregati come:

    • /users/{id}/stats

    • /topics/{id}/stats

7. FlessibilitĂ  degli Avatar Utente

Limitazione attuale:

  • gli avatar sono strettamente accoppiati al sistema di upload di Discourse

Richiesta:

  • permettere URL di avatar esterni (S3 / CDN / provider di autenticazione esterni)

  • supportare:

    • external_avatar_url

Ciò aiuterebbe con:

  • sistemi SSO

  • provider di identitĂ  headless

8. Chiavi API: Chiavi Admin vs Chiavi Utente

Necessaria chiarificazione nella documentazione:

Differenza tra:

  • chiave API admin

  • chiave API utente (creata tramite /admin/api/keys o endpoint API utente)

Domande:

  • regole di ciclo di vita e scadenza

  • regole di revoca per utente rispetto a globali

  • limitazioni di ambito di sicurezza per tipo

Questo è critico quando si costruiscono integrazioni di livello production.

Considerazioni Finali

L’API di Discourse è già potente, ma sembra ottimizzata per “l’uso di forum renderizzati lato server” più che per “architetture headless / guidate dal frontend”.

I framework moderni (Next.js, Remix, ecc.) beneficiano molto di:

  • meno round trip

  • confini dei dati piĂą chiari

  • regole di caching prevedibili

  • migliori endpoint di aggregazione

Sarei felice di ricevere feedback dai maintainer o da altri che stanno costruendo configurazioni Discourse headless.

Grazie :folded_hands:

2

Qualcos’altro che ho notato e che mi infastidisce è che alcuni endpoint sono “protetti” usando la codifica form invece del JSON, forse per scoraggiare le persone dall’interferire con l’API? L’esempio migliore è l’API di tracciamento dei click sui link, che immagino abbia senso come protezione, ma chiunque può comunque abusarne se lo vuole davvero, quindi alla fine è solo più difficile per gli sviluppatori fare cose con essa.