Fondamentalement, ce n’est pas un problème de documentation, c’est un problème d’implémentation.
@avdi a soulevé ce point il y a des années et il y a un large consensus interne sur le fait que la bonne voie à suivre est une API JSON/REST versionnée avec des paramètres et des structures de données cohérents.
Actuellement, l’API que nous fournissons est notre API interne. Elle est 100 % complète et exhaustive, mais elle est maladroite et changeante. Les structures qu’elle renvoie et les points de terminaison sont tous optimisés pour piloter l’application Ember côté client. Elle évolue et change de forme au fil des mois, ce qui la rend difficile à utiliser pour des tâches critiques. La construire est plus complexe qu’elle ne devrait l’être.
Un tout nouvel ensemble de contrôleurs et de routes résoudrait le problème de stabilité ici et nous permettrait de renvoyer des structures qui ont plus de sens pour une API REST. Par exemple :
/api/v0/topic/1234.json pourrait renvoyer une structure beaucoup plus « cohérente avec la pratique générale des API ».
Il y a trop de « préoccupations exclusives à l’application Ember » très compliquées dans notre JSON de sujet :
timeline_lookup, post_stream, tags_descriptions etc… etc…
Cela dit, c’est un projet énorme à entreprendre, nous aurions besoin d’une refonte interne considérable pour nous assurer de ne pas doubler la logique. De plus, les plugins compliquent encore les choses car ils remodèlent une grande partie du comportement interne qui devrait être reflété dans l’API. (que fait assign à ces structures ?)
Je vois certainement que nous nous embarquons dans cette aventure, mais pas dans un avenir proche.