Ich verstehe nicht, warum es keine vollständige Dokumentation für alle API-Endpunkte gibt. Die ursprüngliche Dokumentation wurde im Dezember 2014 veröffentlicht, und hier sind wir sechs Jahre später, und die Dokumentation ist immer noch halb fertig.
Warum ist das so? Der Mangel an guter Dokumentation und der Hinweis, die API reverse-engineeren zu müssen, stellt eine erhebliche Hürde für Entwickler dar, die die API nutzen möchten.
Mit freundlichen Grüßen,
ein frustrierter Entwickler
Kannst du ein paar Beispiele nennen, bei denen du Schwierigkeiten hast oder etwas vermisst?
Dies ist ein aktuelles Thema, da ich eine Warnung in meinem Forum habe: „Wir haben eine API-Anfrage mit einer veralteten Authentifizierungsmethode erkannt.
Die ordnungsgemäße API-Authentifizierung wird in der Dokumentation ganz oben behandelt. Kurz gesagt: Sie müssen HTTP-Header verwenden, um den API-Schlüssel und den Benutzernamen bereitzustellen, anstatt URL-Parameter zu nutzen.
@justin Mein konkretes Beispiel ist, dass ich langsam dabei bin, eine Python-Wrapper für die Discourse-API zu entwickeln, und ich finde das Fehlen einer ordentlichen Dokumentation überwältigend. Ich muss bereits jeden einzelnen Endpunkt manuell testen, doch viele dieser Endpunkte sind entweder nicht dokumentiert oder falsch dokumentiert.
Ganz oben in der Dokumentation steht ausdrücklich, dass die API nicht vollständig dokumentiert ist. Ich möchte wissen: Warum?
Siehe Reverse engineer the Discourse API
Warum ist nicht jedes einzelne Sandkorn am Strand „vollständig dokumentiert“? 
Aus Interesse: Warum unterstützen Sie nicht einfach das, was erforderlich ist, bis Sie auf eine neue, nicht unterstützte Anforderung stoßen, die Sie dann reverse-engineeren? Das ist viel einfacher als das Ziel von 100 % zu verfolgen, und es ist sinnlos, Aufrufe zu umhüllen, die nie verwendet werden? Besonders, da Sie ein sich ständig änderndes Ziel unterstützen. Machen Sie es sich leichter?
Ich verstehe, dass dies rückentwickelt werden kann. Es ist nur etwas frustrierend, das tun zu müssen. Die API wurde von Menschen erstellt, die wissen müssen, wie sie funktioniert. Warum können diese Menschen es nicht aufschreiben, damit andere informiert werden?
Ich finde, das ist keine große Bitte. Gute Dokumentation ist in jedem Projekt entscheidend.
Das ist derzeit der Plan: Ich habe alle dokumentierten Endpunkte in meinem Repository im Branch ‘develop’ gespiegelt und stehe nun an dem Punkt, an dem ich mit Reverse-Engineering beginnen muss.
Ich beginne bereits, zu GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub beizutragen, frage mich aber wirklich, warum das bei einem so etablierten Projekt überhaupt notwendig ist.
Wie bei allem kommt es auf Ressourcen und Prioritäten an. Die API-Oberfläche ist riesig. Technisch gesehen umfasst sie alles – alles wird über die API abgerufen, weshalb Reverse Engineering funktioniert. Wir haben uns entschieden, unsere begrenzte Entwicklungszeit auf Fehlerbehebungen, neue Funktionen, Leistungsverbesserungen usw. zu konzentrieren, anstatt auf die Dokumentation. Unsere Produktstrategie wird maßgeblich von unseren Kunden und unserer Community vorangetrieben. Soweit ich weiß, hat noch nie ein Kunde eine vollständige API-Dokumentation gefordert. Wenn Kunden etwas vermissen oder unklar finden, fügen wir es hinzu. Daher war eine 100-prozentige Abdeckung keine Priorität.
Derzeit werden die API-Dokumente manuell erstellt. Das ist offensichtlich keine nachhaltige Methode, aber im Moment ist es das, was wir haben. Die Umstellung des API-Dokumentationssystems auf eine programmatische Generierung ist ein „To-Do“-Punkt, steht jedoch derzeit für keine bestimmte Veröffentlichung an, sodass es keinen Zeitplan für den Abschluss gibt.