Fundamentalmente, este no es un problema de documentación, es un problema de implementación.
@avdi planteó esto hace años y existe un amplio consenso interno de que el camino correcto a seguir es una API REST/JSON versionada adecuada con parámetros y formas de datos consistentes.
Actualmente, la API que enviamos es nuestra API interna. Está 100% completa y es exhaustiva, pero es torpe y cambia de forma. Las formas que devuelve y los puntos finales están optimizados para impulsar la aplicación Ember del lado del cliente. Evoluciona y cambia de forma a medida que pasan los meses, lo que dificulta depender de ella para tareas de misión crítica. Construir sobre ella es más complejo de lo necesario.
Un conjunto completamente nuevo de controladores y rutas resolvería el problema de estabilidad aquí y nos permitiría devolver formas que tengan más sentido para una API REST. Por ejemplo:
/api/v0/topic/1234.json podría devolver una forma mucho más “consistente con la práctica general de API”.
Hay demasiadas “preocupaciones exclusivas del cliente Ember” muy complicadas en nuestro JSON de temas:
timeline_lookup, post_stream, tags_descriptions, etc., etc.
Dicho esto, este es un proyecto masivo para emprender, necesitaríamos una gran cantidad de rediseño interno para asegurarnos de no duplicar la lógica. Además, los complementos complican esto aún más porque remodelan gran parte del comportamiento interno que debería reflejarse en la API. (¿qué hace assign a estas formas?)
Ciertamente veo que nos embarcamos en esta aventura, pero no en un futuro cercano.