Amélioration de la documentation de l'API Discourse pour créer une communauté frontend entièrement personnalisée

Dev
1

Bonjour à tous :waving_hand:

Je suis en train de développer un frontend personnalisé en utilisant Discourse comme backend headless (architecture basée sur Next.js), et je souhaite partager quelques lacunes pratiques que j’ai rencontrées dans la conception actuelle de l’API, du point de vue d’une intégration réelle.

Il ne s’agit pas d’une critique de Discourse lui-même (il est puissant et flexible), mais plutôt d’un retour d’expérience pour améliorer l’expérience développeur (DX) dans les architectures modernes combinant frontend et API.

1. Pagination et structure des posts de sujet

Problème actuel :

  • La pagination n’est pas toujours cohérente entre les différents endpoints

  • Les posts d’un sujet (/t/{id}.json) mélangent :

    • le post original

    • les réponses

    • les métadonnées internes

  • Cela rend plus difficile la mise en place d’un défilement infini propre ou d’un état normalisé (Redux/Zustand/React Query)

Suggestion :

  • Proposer une séparation plus claire ou des drapeaux de requête optionnels tels que :

    • ?include_first_post=true|false

    • ?posts_only=replies

    • Soutien de la pagination basée sur curseur (au lieu de la pagination par page uniquement)

2. Réponses vs structure du sujet

Actuellement :

  • Les réponses sont intégrées dans la réponse du sujet

  • Aucune séparation claire entre :

    • les “métadonnées du sujet”

    • le “flux de posts”

Cela entraîne :

  • une logique de parsing supplémentaire dans le frontend

  • des duplications lors de la normalisation de l’état

Suggestion :

  • Proposer des endpoints dédiés tels que :

    • /t/{id}/posts

    • /t/{id}/replies

    • ou prendre en charge le filtrage directement dans /t/{id}.json

3. Absence de documentation au niveau des champs dans la réponse de l’API

Par exemple, dans la réponse d’un sujet :

  • created_at

  • bumped_at

  • last_posted_at

  • updated_at

Ces champs ne sont pas toujours clairement différenciés.

Problème :

  • Les développeurs interprètent souvent incorrectement :

    • bumped_at par rapport à updated_at

    • ce qui déclenche une “activité du sujet”

Suggestion :

  • Ajouter une documentation de schéma inline ou des métadonnées de style OpenAPI :

    • signification de chaque champ

    • explication du cycle de vie

4. Incohérences dans les statistiques et la mise en cache

Problèmes :

  • posts_count, reply_count, participants_count sont parfois en retard par rapport aux données en temps réel

  • Forte dépendance aux compteurs mis en cache

Impact :

  • Interface utilisateur inexacte (en particulier pour les tableaux de bord / pages d’analyse)

  • Nécessite des appels API supplémentaires pour valider l’état

Suggestion :

  • Ajouter un indicateur “temps réel vs mis en cache” ou une variante d’endpoint

  • Ou fournir des mises à jour par webhook/événement pour les compteurs

5. Lacunes dans l’intégration du sitemap, du SEO et des frameworks

Lors de l’intégration avec des frameworks modernes (Next.js, Nuxt, etc.) :

Problèmes :

  • Aucun endpoint unifié pour :

    • les sujets mis à jour pour la génération de sitemap

    • le suivi des dernières modifications au niveau des catégories

    • le support complet de l’indexation des posts

Les développeurs se retrouvent à faire :

  • plusieurs appels API par catégorie

  • des comparaisons manuelles pour updated_at

  • un crawl par pagination pour détecter les mises à jour

Suggestion :

  • Ajouter des endpoints dédiés :

    • /categories/updated

    • /topics/changes?since=timestamp

    • /sitemap.json (flux de sitemap piloté par l’API)

6. Métriques et agrégations utilisateur manquantes

Données couramment nécessaires :

  • nombre total de likes reçus par utilisateur

  • nombre total de likes donnés

  • répartition des réactions par post/utilisateur

  • statistiques d’engagement par catégorie

Problème actuel :

  • nécessite plusieurs endpoints + agrégation côté frontend

Suggestion :

  • Ajouter des endpoints agrégés tels que :

    • /users/{id}/stats

    • /topics/{id}/stats

7. Flexibilité des avatars utilisateur

Limitation actuelle :

  • les avatars sont étroitement couplés au système de téléchargement de Discourse

Demande :

  • permettre des URLs d’avatars externes (S3 / CDN / fournisseurs d’authentification externes)

  • supporter :

    • external_avatar_url

Cela aiderait avec :

  • les systèmes SSO

  • les fournisseurs d’identité headless

8. Clés API : clés administrateur vs clés utilisateur

Nécessité de clarifications dans la documentation :

Différence entre :

  • clé API administrateur

  • clé API utilisateur (créée via /admin/api/keys ou les endpoints API utilisateur)

Questions :

  • règles de cycle de vie et d’expiration

  • règles de révocation par utilisateur vs globales

  • limitations de portée de sécurité par type

Ceci est crucial lors de la création d’intégrations de niveau production.

Réflexions finales

L’API de Discourse est déjà puissante, mais elle semble optimisée pour une “utilisation de forum rendu côté serveur” plutôt que pour une “architecture headless / pilotée par le frontend”.

Les frameworks modernes (Next.js, Remix, etc.) bénéficient grandement de :

  • moins d’allers-retours

  • des limites de données plus claires

  • des règles de mise en cache prévisibles

  • de meilleurs endpoints d’agrégation

J’aimerais beaucoup avoir des retours des mainteneurs ou d’autres personnes qui construisent des configurations Discourse headless.

Merci :folded_hands:

2

Autre chose qui m’agace : certains endpoints sont « protégés » via un encodage de formulaire plutôt que du JSON, peut-être pour décourager les gens de manipuler l’API ? Le meilleur exemple est l’API de suivi des clics sur les liens, ce qui, je suppose, a du sens en tant que protection, mais n’importe qui peut toujours l’utiliser à mauvais escient s’il le veut vraiment. Au final, cela rend simplement les choses plus difficiles pour les développeurs qui veulent faire des choses avec.