По своей сути это не проблема документации, а проблема реализации.
@avdi поднимал этот вопрос ещё несколько лет назад, и внутри компании сложился широкий консенсус относительно того, что правильный путь вперёд — это создание полноценного версионированного JSON/REST API с согласованными параметрами и структурами данных.
В настоящее время мы предоставляем наше внутреннее API. Оно на 100% полно и исчерпывающе, но неудобно и постоянно меняет свою форму. Возвращаемые им структуры и конечные точки оптимизированы для работы клиентского приложения на Ember. Со временем они меняются и трансформируются, что затрудняет их использование для выполнения критически важных задач. Разработка на его основе оказывается сложнее, чем необходимо.
Создание совершенно нового набора контроллеров и маршрутов решило бы проблему стабильности и позволило бы возвращать структуры, более логичные для REST API. Например:
/api/v0/topic/1234.json мог бы возвращать структуру, гораздо более «согласованную с общепринятой практикой работы с API».
В нашем JSON для тем содержится слишком много очень сложных деталей, относящихся исключительно к клиенту Ember:
timeline_lookup, post_stream, tags_descriptions и так далее…
Тем не менее, это масштабный проект, за который нам предстоит взяться. Нам потребуется значительная внутренняя переработка, чтобы избежать дублирования логики. Кроме того, плагины усложняют задачу, поскольку они меняют множество внутренних механизмов, которые должны быть отражены в API. (Как функция assign влияет на эти структуры?)
Я уверен, что мы в конечном итоге займёмся этим, но не в ближайшем будущем.