Ich suche nach einer Möglichkeit, eine definitive Liste der API-Endpunkte zu erhalten, die in meiner Discourse-Instanz verfügbar sind. Es kann manchmal schwierig sein zu wissen, welche APIs mir zur Verfügung stehen, wenn ich eine Integration in die Plattform erstellen möchte.
5 „Gefällt mir“
Ich glaube nicht, dass das technisch möglich ist. Discourse hat keine API-Discovery-Route (zum Beispiel etwas Ähnliches wie die WordPress /wp-json-Route). Das Nächstliegende, das mir bekannt ist, sind die Dokumentationen unter https://docs.discourse.org/.
Für Integrationen, die nicht in den Dokumenten behandelt werden, ist der wahrscheinlich schnellste Weg, um herauszufinden, ob sie machbar sind, hier nachzufragen, wie ein bestimmtes Ziel erreicht werden kann. Die allgemeine Regel mit der API ist, dass alles, was über die Discourse-Benutzeroberfläche getan werden kann, auch über die API getan werden kann.
9 „Gefällt mir“
Danke für die Antwort, Simon! Ich kenne docs.discourse.org (was, lustigerweise, nicht die offiziellen Dokumente, sondern die API-Spezifikationen sind).
Ich bin auch damit vertraut, meine Browserkonsole zum Erfassen von Anfragen zu verwenden, sowie das Durchsuchen von routes.rb-Dateien.
Wie Sie sich vorstellen können, sind die beiden oben genannten Optionen ziemlich mühsam und nicht gerade benutzerfreundlich. Für diejenigen von uns, die schnelle, tiefe Integrationen aufbauen möchten – insbesondere wenn wir andere Teams in unserem Unternehmen oder Drittanbieter haben, die integrieren möchten –, war die Aufforderung, die oben genannten Dinge zu tun, mit einer furchtbar schlechten Resonanz verbunden.
Obwohl ich mir der Flexibilität der Möglichkeiten von Discourse bewusst bin, ist die Entwicklung auf oder die Integration mit der Plattform, gelinde gesagt, ein Kampf. Als letzten Ausweg hoffte ich, dass es vielleicht einen programmatischen Weg gäbe, die öffentlichen APIs zu aggregieren.
7 „Gefällt mir“
Die definitive Quelle, abgesehen von der Quelle selbst, ist das Reverse Engineering der Discourse API.
Alles, was Sie im Frontend tun können, können Sie auch mit der API tun. Es gibt nur sehr wenige Dinge, die Sie nur mit der API tun können.
3 „Gefällt mir“
Können Sie genauer erläutern, was Sie damit meinen?
Während Simons Punkt, dass diese keine APIs abdecken, die durch Erweiterungen von Discourse implementiert werden (z. B. Plugins), sind diese Dokumente in dem Sinne offiziell, als dass wir sie pflegen.
Das heißt nicht, dass wir nicht viel Spielraum zur Verbesserung haben, was die Dokumentation der serverseitigen API und die API selbst betrifft, aber ich wollte Ihr Feedback zu der Dokumentation, die dort existiert, etwas besser verstehen.
1 „Gefällt mir“
Gerne! Das ist wahrscheinlich mehr, als Sie verlangt haben 
Ich glaube, Sie bewahren Ihre offizielle Produktdokumentation hier auf, richtig?
Ich würde sagen, die Nuance ist, dass API-Spezifikationen eine Untermenge der Dokumentation sind. Daher vergesse ich immer und es überrascht mich kurz, wenn ich jemanden auf docs.discourse.org verweise und vergesse, dass dieser Link nicht zu Discourse-Dokumenten führt… er führt zu einer begrenzten Auswahl an API-Spezifikationen.
Daher sage ich ihnen eine Version von:
Danke für das heutige Treffen, ich freue mich, dass Sie daran interessiert sind, welche Art von Erfahrung Sie für unsere Benutzer mit der neuen Netwrix Community aufbauen können!
Die Dokumente befinden sich tatsächlich unter https://meta.discourse.org/c/documentation/10.
docs.discourse.org ist nicht wirklich ihre Dokumentation, sondern ihre API-Spezifikationen. Ich weiß, dass Sie nach der Integration mit der neuen Community gefragt haben, die wir aufbauen. Leider habe ich keine Seite, auf die ich Sie verweisen könnte, die die gesamte Funktionalität von Discourse zeigt, aber Sie können docs.discourse.org besuchen, um eine Vorstellung davon zu bekommen, was möglich ist.
Was ich in diesem Szenario tue, da ich ihnen keine definitive Liste der vorhandenen Endpunkte geben kann, ist, dass ich ihnen einfach sage: „Gehen Sie davon aus, dass alles möglich ist, was Sie sich vorstellen können. Ich werde nachsehen, was Discourse kann, und wir können es bei Bedarf von dort aus einschränken.“
Aber es wäre großartig, wenn alle APIs in den Spezifikationen aufgeführt wären, oder?
Mehr Kontext…
Es wäre seltsam, wenn ich ein Auto kaufen würde und sie mir ein Blatt mit Funktionen gäben und ich fragte: „Großartig! Ist das dann alles?“
„Nun, nein… aber wenn Sie einfach unter die Haube schauen und einige der 12-V-Kabel und Schlauchschellen am Motor verfolgen, sollten Sie sehen können, womit sie verbunden sind, und rückentwickeln können, was es sonst noch tut.“
Sicher, der Mechaniker/Entwickler/technisch versierte Mensch kann das in diesem Szenario tun. Aber nicht jeder 
Außerdem möchte ich als Entwickler nicht:
- Ruby lernen, um zu sehen, wo Routen existieren könnten
- Alle routes.rb-Dateien rückentwickeln, um eine Vorstellung von den verfügbaren Endpunkten zu bekommen
- Diese Rückentwicklung weiter verfeinern, um herauszufinden, welche Eingaben sie erfordern, welche Objektstruktur die Ausgabe hat
- Nachsehen, welche Plugins ich habe
- Dies in ihren routes.rb-Dateien wiederholen (glaube ich? Ich spreche kein Ruby, also bin ich mir nicht sicher)
- …und 6 Monate später habe ich zwischen meinem Hauptjob und diesem eine Antwort.
Ich sage das alles liebevoll – es gibt heute keine Plattform, die mit den Fähigkeiten der Discourse-Plattform mithalten kann. Punkt. Es ist das robusteste, leistungsfähigste, flexibelste und kostengünstigste Produkt auf dem Markt und Lichtjahre über der Konkurrenz.
Seine Mängel liegen nicht in seiner Robustheit, Leistung und Flexibilität. Tatsächlich sind dies einige der größten Vorteile von Discourse, die Konkurrenzprodukte nur schwer oder gar nicht nachahmen können.
- Es ist nicht so, dass seine APIs nicht großartig sind – es ist nur schwierig, sie zu finden.
- Es sind nicht Admin-Panels mit vielen Optionen, die die Einführung erschweren, sondern mangelnde Aufklärung und Namen von Admin-Einstellungen wie
Nur erster Beitrag, die bestenfalls mehrdeutig sind. - Es ist nicht seine robuste, aber einfache (und perfekte!) Implementierung einer Community-Tool-Struktur aus Kategorien, Themen und Tags, aber die Informationen fehlen, um Benutzer zu schulen und zu inspirieren, dass es keine Kategorie sein muss, sondern ein Blog, ein Produktankündigungs-Board oder ein Ideenportal… und sie müssen keine Themen sein, sondern können Blogs, Produktankündigungen und Ideen sein.
Das ist das einzige, was Discourse als Produkt für mich vermisst: der Schliff – die letzten Details.
9/10, würde es wieder kaufen.
7 „Gefällt mir“
OK, ich glaube, ich verstehe es jetzt besser, danke.
Was folgt, sind meine eigenen Meinungen – ich habe sie nicht mit Leuten besprochen, die sich besser auskennen als ich, daher werde ich vielleicht auf einige Dinge korrigiert, die ich hier falsch mache.
Auch unsere Dokumentation entwickelt sich weiter. Wir haben bedeutende Fortschritte gemacht, aber es liegt noch ein langer Weg vor uns. Lassen Sie mich versuchen, ein wenig zusammenzufassen.
Zuerst würde ich die Dinge als eine Art übergeordnetes mentales Modell so beschreiben:
- Unser Haupteinstiegspunkt für die Dokumentation ist hier, wie Sie richtig bemerkt haben: Documentation - Discourse Meta
- Für die Entwicklerdokumentation ist sie hier oder vielleicht noch besser hier: Introduction to Discourse Development
- API-Dokumente sind eine Teilmenge der Entwicklerdokumente und befinden sich hier: https://docs.discourse.org/
- Für die Entwicklerdokumentation ist sie hier oder vielleicht noch besser hier: Introduction to Discourse Development
Ich würde die API-Dokumente eher als Dokumente denn als Spezifikationen bezeichnen, aber ich stimme zu, dass sie immer noch eine Teilmenge unserer Entwicklerdokumente sind. Die URL für diese Dokumente ist seltsam… es wäre sinnvoller, wenn unsere vollständige Dokumentation dort leben würde oder wenn dies eine Weiterleitung zu https://meta.discourse.org/c/documentation/10 wäre, und wenn es ein klares Wegweiser von Introduction to Discourse Development zu den API-Dokumenten gäbe.
Unsere Entwicklerdokumentation wird selbst verbessert. Die Commit-Historie hier erzählt wahrscheinlich die beste Geschichte darüber, wohin die bisherigen Bemühungen geflossen sind: Commits · discourse/discourse-developer-docs · GitHub
Die API-Dokumente könnten als unvollständig beschrieben werden, aber wir haben noch Arbeit vor uns, um unsere Geschichte hier zu klären. Früher haben wir auf „Reverse Engineering der API“ verwiesen, aber ich stimme zu, dass das keine gute Geschichte ist. Es ist in Ordnung, auf eigene Gefahr zu basteln, aber es kann Fälle geben, in denen Endpunkte, die dort nicht aufgeführt sind, wahrscheinlich besser nicht genutzt werden sollten.
Die serverseitige API ist in erster Linie für unsere Frontend-Anwendung gedacht. Im Frontend bieten wir eine JavaScript-API an, die eine bessere Schnittstelle darstellt, da sie Änderungen am Backend ausblenden kann: Using the JS API
Welche Stabilitätsgarantien können wir also für unsere Backend-API geben?
Ich denke, das ist eine Verantwortung, die diese API-Dokumente sollten angehen. Idealerweise ist das, was dort dokumentiert ist, eine Teilmenge aller Endpunkte, die wir unterstützen, aber eine absichtliche Teilmenge, die wir für andere, die Integrationen erstellen, unterstützen wollen, während Dinge, die dort nicht aufgeführt sind, absichtlich nicht als Dinge dokumentiert sind, die nur für unser Frontend bestimmt sind und sich ohne Vorankündigung ändern können.
Idealerweise (in meinen Augen) würden wir die Dokumentation in den Quellcode integrieren, so dass die Dokumentation selbst getestet wird, mit Plugins erweiterbar ist und von der App selbst bereitgestellt wird, damit sie mit der Instanz synchron ist, die dokumentiert wird – auf diese Weise könnten Sie die API-Dokumentation für eine bestimmte Website anzeigen und die Dokumentation für die Version sehen, die sie ausführt, mit den tatsächlich installierten und aktivierten Plugins.
Ich weiß, dass andere intern viele Diskussionen über weitere Ideen zur Verbesserung unserer serverseitigen API-Geschichte geführt haben.
Wir konnten uns in diesem Bereich noch nicht viel priorisieren, da unser Hauptaugenmerk in den letzten Jahren auf der Modernisierung unseres Frontends lag.
Ich bin mir nicht sicher, wann sich das wahrscheinlich ändern wird, aber wir werden Ausschau nach kleineren Dingen halten, die wir tun können, um die serverseitige API-Geschichte weiter voranzutreiben. Wenn spezifische Fragen auftauchen, können wir diese vielleicht als Anlass nehmen, in der Zwischenzeit gezieltere Verbesserungen vorzunehmen.
5 „Gefällt mir“
Stabilitätsgarantien sollten durch eine einfache API-Versionierung angegangen werden.
In diesem Thema geht es nicht darum, wo die Dokumentation lebt – es geht darum, wie die API dokumentiert ist. Was fehlt, ist ein standardisiertes, maschinenlesbares Format wie OpenAPI.
Diese Abwesenheit, zusammen mit dem Mangel an Versionierung, macht die Integrationsarbeit schwieriger und fragiler, als sie sein sollte. Selbst ein grundlegendes OpenAPI-Schema für die dokumentierten Endpunkte wäre sehr hilfreich.
3 „Gefällt mir“
Grundsätzlich ist dies kein Dokumentationsproblem, sondern ein Implementierungsproblem.
@avdi hat dies vor Jahren angesprochen und es gibt einen breiten internen Konsens, dass der richtige Weg eine ordnungsgemäße versionierte JSON/REST-API mit konsistenten Parametern und Datenformen ist.
Derzeit ist die API, die wir ausliefern, unsere interne API. Sie ist zu 100 % vollständig und umfassend, aber sie ist umständlich und formveränderlich. Die Formen, die sie zurückgibt, und die Endpunkte sind alle für die Steuerung der clientseitigen Ember-App optimiert. Sie entwickelt sich und ändert ihre Form im Laufe der Monate, was es schwierig macht, sich für geschäftskritische Aufgaben darauf zu verlassen. Der Aufbau darauf ist komplexer als nötig.
Ein brandneuer Satz von Controllern und Routen würde das Stabilitätsproblem hier lösen und uns ermöglichen, Formen zurückzugeben, die für eine REST-API sinnvoller sind. Zum Beispiel:
/api/v0/topic/1234.json könnte eine Form zurückgeben, die „konsistenter mit allgemeinen API-Praktiken“ ist.
Es gibt zu viele sehr komplizierte „nur für Ember-Clients relevante Anliegen“ in unserem Topic-JSON:
timeline_lookup, post_stream, tags_descriptions usw. usw.
Das gesagt, ist dies ein riesiges Projekt, das wir in Angriff nehmen müssten. Wir bräuchten eine Menge interner Neugestaltung, um sicherzustellen, dass wir keine Logik doppelt anwenden. Zusätzlich machen Plugins dies noch komplizierter, da sie viel internes Verhalten umformen, das in der API reflektiert werden müsste. (Was bewirkt die Zuweisung mit diesen Formen?)
Ich sehe sicherlich, dass wir uns auf dieses Abenteuer einlassen, aber nicht in naher Zukunft.
10 „Gefällt mir“
Ich halte es für absolut vernünftig, dass die Umstellung Zeit braucht. Ich leitete die Entwicklerbeziehungen in meinem letzten Unternehmen und meine Güte… es dauerte über zwei Jahre, bis unsere APIs in einem verbesserten Zustand waren. So viele komplexe Dinge zu berücksichtigen (und das Engineering hasste die Idee, einen stabilen Endpunkt zu schaffen, der sich nicht ändern konnte!)
Ich glaube jedoch, dass kleinere Änderungen im Laufe der Zeit und in kürzeren Zeiträumen ebenfalls möglich sind. Ich habe mir zugegebenermaßen nicht angesehen, wie Ihre Routen (oder wie Routen in Ruby) definiert sind – aber ich gehe davon aus, dass einige leicht zu handhabende Dinge ziemlich einfach erledigt werden könnten. Zum Beispiel:
Ich kann nicht für alle sprechen, aber ich habe das Gefühl, dass es schon ein großer Gewinn wäre, wenn die Endpunkte in Ihrer aktuellen API-Spezifikation vorhanden wären – auch wenn Sie keine Beschreibungen und Beispiele hätten und auch wenn das Antwortmodell fließend wäre. Allein das Wissen, dass etwas existiert, ist manchmal die halbe Miete.
5 „Gefällt mir“
Die API-Dokumentation liegt im OpenAPI-Format vor?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 „Gefällt mir“
Ich muss beschämend zugeben, dass mir das noch nie aufgefallen ist…
Danke @blake, dass du darauf hingewiesen hast.
2 „Gefällt mir“