Fondamentalmente questo non è un problema di documentazione, è un problema di implementazione.
@avdi lo ha sollevato anni fa e c’è un ampio consenso interno sul fatto che la giusta via da seguire sia una corretta API JSON/REST versionata con parametri e forme dei dati coerenti.
Attualmente, l’API che forniamo è la nostra API interna. È completa al 100% ed esaustiva, ma è scomoda e cambia forma. Le forme che restituisce e gli endpoint sono tutti ottimizzati per guidare l’applicazione Ember lato client. Si evolve e cambia forma con il passare dei mesi, il che la rende difficile da utilizzare per attività mission-critical. Costruire su di essa è più complesso del necessario.
Una serie completamente nuova di controller e route risolverebbe il problema della stabilità qui e ci permetterebbe di restituire forme che abbiano più senso per un’API REST. Ad esempio:
/api/v0/topic/1234.json potrebbe restituire una forma molto più “coerente con la pratica generale delle API”.
Ci sono troppe “preoccupazioni esclusive per il client Ember” molto complicate nel nostro JSON di argomenti:
timeline_lookup, post_stream, tags_descriptions ecc… ecc…
Detto questo, questo è un progetto enorme da intraprendere, avremmo bisogno di una grande riprogettazione interna per garantire di non duplicare la logica. Inoltre, i plugin rendono questo aspetto ancora più complicato perché rimodellano molti comportamenti interni che dovrebbero essere riflessi nell’API. (cosa fa assign a queste forme?)
Certamente vedo che intraprenderemo questa avventura, ma non nel prossimo futuro.