Sto cercando un modo per ottenere un elenco definitivo degli endpoint API disponibili nella mia istanza Discourse. A volte può essere difficile sapere quali API sono disponibili quando si cerca di creare un’integrazione nella piattaforma.
5 Mi Piace
Non credo sia tecnicamente possibile. Discourse non dispone di un percorso di discovery delle API (ad esempio, qualcosa di simile al percorso /wp-json di WordPress). La cosa più vicina che conosco è la documentazione su https://docs.discourse.org/.
Per le integrazioni non coperte dalla documentazione, probabilmente il modo più rapido per capire se sono fattibili è chiedere qui come raggiungere un obiettivo specifico. La regola generale con l’API è che tutto ciò che può essere fatto tramite l’interfaccia utente di Discourse può essere fatto anche tramite l’API.
9 Mi Piace
Apprezzo la risposta, Simon! Ho familiarità con docs.discourse.org (che, per inciso, non sono i documenti ufficiali ma le specifiche API).
Ho anche familiarità con l’uso della console del browser per acquisire richieste e con l’analisi dei file routes.rb.
Come puoi immaginare, però, le due opzioni sopra sono piuttosto noiose e non molto user-friendly. Per quelli di noi che cercano di costruire integrazioni profonde rapidamente, specialmente se abbiamo altri team nella nostra azienda o fornitori terzi che vogliono integrarsi… dire loro di fare le cose di cui sopra ha avuto una risposta terribilmente scarsa.
Sebbene sia consapevole della flessibilità delle capacità di Discourse, sviluppare o integrare con la piattaforma è a dir poco una battaglia in salita. Come ultimo tentativo, speravo ci fosse un modo programmatico per aggregare le API pubbliche.
7 Mi Piace
La fonte definitiva, oltre alla fonte, è Ingegnerizzare al contrario l’API di Discourse.
Tutto ciò che puoi fare sul front-end puoi farlo con l’API. Ci sono pochissime cose che puoi fare solo con l’API.
3 Mi Piace
Puoi chiarire cosa intendi con questo un po’ di più?
Mentre il punto di Simon sul fatto che questi non coprano le API implementate da estensioni di Discourse (ad esempio, plugin), questi documenti sono ufficiali nel senso che li manteniamo.
Ciò non significa che non abbiamo un margine di miglioramento per quanto riguarda la documentazione dell’API lato server e l’API stessa, ma vorrei capire meglio il tuo feedback sulla documentazione che esiste già.
1 Mi Piace
Certamente! Questo è probabilmente più di quanto tu abbia chiesto 
Penso che tu conservi la documentazione ufficiale del prodotto qui, corretto?
Direi che la sfumatura è che le specifiche dell’API sono un sottoinsieme della documentazione. Quindi dimentico sempre e mi coglie di sorpresa per un attimo quando indirizzo qualcuno a docs.discourse.org e dimentico che quel link non porta alla documentazione di Discourse… porta a un insieme limitato di specifiche API.
Quindi dico loro una versione di:
Grazie per esserti incontrato oggi, sono lieto che tu sia interessato a vedere quale tipo di esperienza puoi creare per i nostri utenti utilizzando la nuova Community Netwrix!
La documentazione si trova in realtà su https://meta.discourse.org/c/documentation/10.
docs.discourse.org non è in realtà la loro documentazione, ma le loro specifiche API. So che hai chiesto informazioni sull’integrazione con la nuova community che stiamo costruendo. Sfortunatamente non ho una pagina a cui potrei indirizzarti che mostri tutte le funzionalità che Discourse offre, ma puoi andare su docs.discourse.org per farti un’idea di solo alcune delle possibilità.
Quello che faccio in questo scenario, poiché non posso fornire loro un elenco definitivo degli endpoint esistenti, è semplicemente dire loro: “Supponi che tutto ciò che puoi concepire sia possibile. Andrò a vedere cosa può fare Discourse e, se necessario, lo ridurremo da lì”.
Ma sarebbe davvero fantastico se tutte le API fossero elencate nelle specifiche, eh?
Ulteriore contesto…
Sarebbe strano se comprassi un’auto e mi dessero un foglio con le caratteristiche e io chiedessi: “Fantastico! È tutto allora?”
“Beh, no… ma se guardi sotto il cofano e segui alcuni dei cablaggi da 12v e i morsetti dei tubi intorno al motore, dovresti essere in grado di vedere a cosa si collegano e fare l’ingegneria inversa di cos’altro fa.”
Certo, il meccanico/sviluppatore/persone tecnicamente preparate in questo scenario possono farlo. Ma non tutti 
Inoltre, anche come sviluppatore, non voglio:
- Imparare Ruby per vedere dove potrebbero esistere le route
- Fare l’ingegneria inversa di tutti i file routes.rb per avere un’idea degli endpoint disponibili
- Affinare ulteriormente quell’ingegneria inversa per capire quali input richiedono, qual è la struttura dell’oggetto dell’output
- Cercare quali plugin ho anche io
- Ripetere sui loro file routes.rb (penso? Non conosco Ruby, quindi non sono sicuro)
- …e 6 mesi dopo, tra il mio lavoro e questo, ho una risposta.
Dico tutto questo con affetto: non esiste oggi una piattaforma che possa competere con le capacità della piattaforma Discourse. Punto. È il prodotto più robusto, potente, flessibile ed economico sul mercato e di gran lunga superiore alla concorrenza.
Le sue mancanze non sono la sua robustezza, potenza e flessibilità. Infatti, questi sono alcuni dei maggiori vantaggi di Discourse che i prodotti concorrenti faticheranno o addirittura falliranno nell’emulare.
- Non è che le sue API non siano eccezionali, è che trovarle è difficile.
- Non sono i pannelli di amministrazione con molte opzioni che rendono difficile l’adozione, ma la mancanza di educazione e nomi di impostazioni di amministrazione come
First post onlyche sono, nella migliore delle ipotesi, ambigui. - Non è la sua solida ma semplice (e perfetta!) implementazione di una struttura di strumenti di community di categorie, argomenti e tag, ma che le informazioni non esistono per educare e ispirare gli utenti che non deve essere una categoria, ma un blog, o una bacheca di annunci di prodotti, o un portale di idee… e non devono essere argomenti ma possono essere blog, annunci di prodotti e idee.
Questa è l’unica cosa che manca a Discourse come prodotto per me: la rifinitura, i dettagli finali.
9/10, lo comprerei di nuovo.
7 Mi Piace
OK, penso di aver capito meglio, grazie.
Ciò che segue sono le mie opinioni personali – non le ho discusse con persone più esperte di me, quindi potrei essere corretto su alcune cose che sto sbagliando qui.
Anche la nostra documentazione delle storie si sta evolvendo. Abbiamo fatto progressi significativi, ma c’è ancora molta strada da fare. Permettetemi di provare a riassumere un po’.
Innanzitutto, come una sorta di modello mentale di livello superiore, descriverei le cose in questo modo:
- Il nostro punto di ingresso principale per la documentazione è qui, come hai sottolineato: Documentation - Discourse Meta
- Per la documentazione per sviluppatori, è qui, o forse ancora meglio, qui: Introduction to Discourse Development
- La documentazione API è un sottoinsieme della documentazione per sviluppatori e si trova qui: https://docs.discourse.org/
Chiamerei la documentazione API docs piuttosto che specs, ma concordo che sono ancora un sottoinsieme della nostra documentazione per sviluppatori. L’URL per tali documenti è strano… avrebbe più senso che la nostra documentazione completa risiedesse lì o che fosse un reindirizzamento a https://meta.discourse.org/c/documentation/10, e che ci fosse un chiaro segnale da Introduction to Discourse Development alla documentazione API.
La nostra documentazione per sviluppatori è essa stessa soggetta a miglioramenti. La cronologia dei commit qui probabilmente racconta la migliore storia su dove è andato lo sforzo finora: Commits · discourse/discourse-developer-docs · GitHub
La documentazione API potrebbe essere descritta come incompleta, ma abbiamo lavoro da fare per mettere a punto la nostra storia qui. In passato, indicavamo di “ingegnerizzare al contrario l’API”, ma concordo che non è una buona storia. Va bene per fare hacking a proprio rischio, ma potrebbero esserci casi in cui gli endpoint non elencati lì è probabilmente meglio non dipenderne.
L’API lato server è destinata principalmente ad essere utilizzata dalla nostra applicazione frontend. Sul frontend, forniamo un’API JavaScript che sarebbe un’interfaccia migliore da utilizzare in quanto può nascondere le modifiche apportate al backend: Using the JS API
Quindi, quali garanzie di stabilità possiamo fare sulla nostra API backend?
Penso che sia una responsabilità che la documentazione API dovrebbe affrontare. Idealmente, ciò che è documentato lì è un sottoinsieme di tutti gli endpoint che supportiamo, ma un sottoinsieme intenzionale che miriamo a supportare per altri che creano integrazioni, mentre le cose non elencate lì sono intenzionalmente non documentate come cose solo destinate al nostro frontend, che potrebbero cambiare senza preavviso.
Idealmente (nella mia mente), avremmo la documentazione integrata nel codice sorgente in modo tale che la documentazione stessa sia sotto test, estensibile con plugin, servita dall’app stessa in modo che sia in sincronia con l’istanza che viene documentata – in quel modo potresti visualizzare la documentazione API per un dato sito e vedere la documentazione per la versione che sta eseguendo, con qualsiasi plugin sia effettivamente installato e abilitato.
So che altri internamente hanno avuto molte discussioni su altre idee per migliorare la nostra storia dell’API lato server.
Non siamo stati in grado di dare priorità a molto in questo spazio ancora, poiché il nostro focus principale quando si tratta di esperienza sviluppatore negli ultimi due anni è stato sulla modernizzazione del nostro frontend.
Non sono sicuro di quando ciò cambierà, ma terremo d’occhio le piccole cose che possiamo fare lungo il percorso per continuare a lavorare sulla storia dell’API lato server. Se emergono domande specifiche, forse possiamo usarle come spunto per apportare miglioramenti più mirati nel frattempo.
5 Mi Piace
Le garanzie di stabilità dovrebbero essere affrontate con un semplice versionamento dell’API.
Questo argomento non riguarda dove si trova la documentazione, ma come viene documentata l’API. Ciò che manca è un formato standardizzato e leggibile dalla macchina come OpenAPI.
Questa assenza, insieme alla mancanza di versionamento, rende il lavoro di integrazione più difficile e fragile di quanto dovrebbe essere. Anche uno schema OpenAPI di base per gli endpoint documentati sarebbe molto utile.
3 Mi Piace
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.
10 Mi Piace
Penso che sia del tutto ragionevole che il cambiamento richieda tempo. Ho gestito le relazioni con gli sviluppatori nella mia ultima azienda e, perbacco… ci sono voluti più di due anni per migliorare le nostre API. C’erano così tante cose complesse da considerare (e l’ingegneria odiava l’idea di creare un endpoint stabile che non potesse cambiare!)
Penso comunque che cambiamenti più piccoli possano avvenire nel tempo e in un lasso di tempo più breve. Ammetto di non aver esaminato come sono definite le tue route (o come sono definite le route in Ruby), ma presumo che alcuni “low-hanging fruit” (frutti facili da cogliere) potrebbero essere gestiti abbastanza facilmente. Ad esempio:
Non posso parlare per tutti, ma penso che anche solo avere gli endpoint presenti nella tua attuale specifica API, anche se non avessi descrizioni ed esempi, e anche se il modello di risposta fosse fluido, sarebbe un’enorme vittoria. A volte, sapere semplicemente che qualcosa esiste è metà della battaglia.
5 Mi Piace
La documentazione API è in formato OpenAPI?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 Mi Piace
Devo vergognosamente ammettere che non me ne sono mai accorto…
Grazie @blake per averlo fatto notare.
2 Mi Piace