Fundamentalmente, este não é um problema de documentação, é um problema de implementação.
@avdi levantou isso anos atrás e há um amplo consenso interno de que o caminho correto a seguir é uma API JSON/REST versionada adequadamente com parâmetros e formatos de dados consistentes.
Atualmente, a API que enviamos é nossa API interna. É 100% completa e exaustiva, mas é desajeitada e muda de formato. Os formatos que ela retorna e os endpoints são otimizados para impulsionar o aplicativo Ember do lado do cliente. Ela evolui e muda de formato à medida que os meses passam, o que a torna difícil de depender para tarefas de missão crítica. Construir sobre ela é mais complexo do que deveria ser.
Um novo conjunto de controladores e rotas resolveria o problema de estabilidade aqui e nos permitiria retornar formatos que façam mais sentido para uma API REST. Por exemplo:
/api/v0/topic/1234.json poderia retornar um formato muito mais “consistente com a prática geral de API”.
Existem muitas “preocupações exclusivas do cliente Ember” muito complicadas em nosso JSON de tópicos:
timeline_lookup, post_stream, tags_descriptions etc… etc…
Dito isso, este é um projeto enorme para embarcar, precisaríamos de muita reformulação interna para garantir que não duplicamos a lógica. Além disso, os plugins tornam isso extra complicado porque eles remodelam muito do comportamento interno, o que precisaria ser refletido na API. (o que assign faz com esses formatos?)
Eu certamente vejo nós embarcando nesta aventura, mas não em um futuro próximo.