Fundamentally this is not a documentation problem, it is a implementation problem.
@avdi raised this years ago and there is broad internal consensus that the correct path forward is a proper versioned JSON/REST API with consistent params and shapes for data.
Currently, the API we ship is our internal API. It is 100% complete and exhaustive, but it is awkward and shape shifting. The shapes it returns and endpoints are all optimised for driving the client-side Ember app. It evolves and changes shape as months pass which makes it tricky to depend upon for mission critical tasks. Building on it is more complex than it needs to be.
A brand new set of controllers and routes would solve the stability problem here and allow us to return shapes that make more sense for a REST API. For example:
/api/v0/topic/1234.json could return a far more “consistent with general API practice” shape.
There are too many very complicated “Ember client only concerns” in our topic json:
timeline_lookup, post_stream, tags_descriptions etc… etc…
That said, this is a massive project to embark upon, we would need a lot of internal redesign to ensure we do not double up on logic. Additionally plugins make this extra complicated cause they reshape a lot of internal behavior which would need to be reflected in the API. (what does assign do to these shapes?)
I certainly see us embarking on this adventure but not any time in the near future.