Verbesserung der Discourse API-Dokumentation für den Aufbau einer vollständig benutzerdefinierten Frontend-Community

Entwickler
1

Hallo zusammen :waving_hand:

Ich baue derzeit ein benutzerdefiniertes Frontend, das Discourse als Headless-Backend nutzt (Next.js-basierte Architektur), und möchte einige praktische Lücken teilen, die ich aus der Perspektive einer echten Integration im aktuellen API-Design festgestellt habe.

Dies ist keine Kritik an Discourse selbst (es ist leistungsstark und flexibel), sondern eher Feedback, um die Developer Experience (DX) für moderne Frontend- und API-getriebene Architekturen zu verbessern.

1. Paginierung & Struktur der Beitragsbeiträge in Themen

Aktuelles Problem:

  • Die Paginierung ist nicht immer über alle Endpunkte hinweg konsistent.

  • Die Beiträge in einem Thema (/t/{id}.json) vermischen:

    • den Originalbeitrag

    • Antworten

    • interne Metadaten

  • Dies erschwert den Aufbau eines sauberen Infinite-Scrolls oder eines normalisierten Zustands (Redux/Zustand/React Query).

Vorschlag:

  • Eine klarere Trennung anbieten oder optionale Abfrage-Flags wie:

    • ?include_first_post=true|false

    • ?posts_only=replies

    • Unterstützung der Paginierung basierend auf Cursor (anstatt nur seitenbasierter Paginierung)

2. Antworten vs. Themenstruktur

Derzeit:

  • Antworten sind in die Themenantwort eingebettet.

  • Es gibt keine klare Trennung zwischen:

    • „Themen-Metadaten“

    • „Beitragsstrom“

Dies führt zu:

  • zusätzlicher Parsing-Logik im Frontend

  • Duplizierung bei der Normalisierung des Zustands

Vorschlag:

  • Dedizierte Endpunkte anbieten wie:

    • /t/{id}/posts

    • /t/{id}/replies

    • oder Unterstützung für Filterung innerhalb von /t/{id}.json

3. Fehlende Feldspezifische Dokumentation in der API-Antwort

Zum Beispiel in der Themenantwort:

  • created_at

  • bumped_at

  • last_posted_at

  • updated_at

Diese werden nicht immer klar unterschieden.

Problem:

  • Entwickler interpretieren oft falsch:

    • bumped_at vs. updated_at

    • was eine „Themenaktivität“ auslöst

Vorschlag:

  • Inline-Schemadokumentation oder Metadaten im OpenAPI-Stil hinzufügen:

    • Bedeutung jedes Feldes

    • Erklärung des Lebenszyklus

4. Inkonsistenzen bei Statistiken & Caching

Probleme:

  • posts_count, reply_count, participants_count hinken den Echtzeitdaten manchmal hinterher.

  • Starke Abhängigkeit von zwischengespeicherten Zählern.

Auswirkung:

  • Ungenaue Benutzeroberfläche (insbesondere für Dashboards / Analytik-Seiten).

  • Erfordert zusätzliche API-Aufrufe zur Validierung des Zustands.

Vorschlag:

  • Einen Indikator „Echtzeit vs. zwischengespeichert“ oder eine Endpunktvariante hinzufügen.

  • Oder Webhooks/eventgesteuerte Updates für Zähler bereitstellen.

5. Lücken bei Sitemap, SEO & Framework-Integration

Bei der Integration mit modernen Frameworks (Next.js, Nuxt, etc.):

Probleme:

  • Keine einheitliche API für:

    • aktualisierte Themen zur Sitemap-Generierung

    • Verfolgung der letzten Änderungen auf Kategorienebene

    • Unterstützung der vollständigen Indexierung von Beiträgen

Entwickler müssen am Ende:

  • mehrere API-Aufrufe pro Kategorie durchführen

  • manuelle Differenzierung für updated_at vornehmen

  • Paginierung durchsuchen, um Updates zu erkennen.

Vorschlag:

  • Dedizierte Endpunkte hinzufügen:

    • /categories/updated

    • /topics/changes?since=timestamp

    • /sitemap.json (API-gesteuertes Sitemap-Feed)

6. Fehlende Benutzermetriken & Aggregationen

Häufig benötigte Daten:

  • Gesamtanzahl der erhaltenen Likes pro Benutzer

  • Gesamtanzahl der vergebenen Likes

  • Aufschlüsselung der Reaktionen pro Beitrag/Benutzer

  • Engagement-Statistiken pro Kategorie

Aktuelles Problem:

  • Erfordert mehrere Endpunkte + Aggregation im Frontend.

Vorschlag:

  • Aggregierte Endpunkte hinzufügen wie:

    • /users/{id}/stats

    • /topics/{id}/stats

7. Flexibilität bei Benutzer-Avataren

Aktuelle Einschränkung:

  • Avatare sind eng mit dem Discourse-Upload-System verknüpft.

Anfrage:

  • Erlaubung externer Avatar-URLs (S3 / CDN / externe Authentifizierungsanbieter).

  • Unterstützung von:

    • external_avatar_url

Dies würde helfen bei:

  • SSO-Systemen

  • Headless-Identitätsanbietern

8. API-Schlüssel: Admin vs. Benutzer-Schlüssel

Klärung in der Dokumentation erforderlich:

Unterschied zwischen:

  • Admin-API-Schlüssel

  • Benutzer-API-Schlüssel (erstellt über /admin/api/keys oder Benutzer-API-Endpunkte).

Fragen:

  • Lebenszyklus & Ablaufregeln

  • Widerrufsregeln pro Benutzer vs. global

  • Sicherheitsbereichseinschränkungen pro Typ

Dies ist entscheidend beim Aufbau produktionsreifer Integrationen.

Abschließende Gedanken

Die Discourse-API ist bereits leistungsstark, wirkt aber eher für „servergerenderte Forum-Nutzung“ optimiert als für „Headless-/Frontend-getriebene Architekturen“.

Moderne Frameworks (Next.js, Remix, etc.) profitieren stark von:

  • weniger Roundtrips

  • klareren Daten-Grenzen

  • vorhersehbaren Caching-Regeln

  • besseren Aggregations-Endpunkten

Ich würde mich über Feedback von Maintainern oder anderen freuen, die Headless-Discourse-Setups aufbauen.

Danke :folded_hands:

2

Etwas anderes, das mir aufgefallen ist und mich nervt, ist, dass einige Endpunkte statt mit JSON mit Form-Encoding „geschützt