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.