Spero di chiarire quando e per quali scopi operano i due sistemi di autenticazione dell’API di Discourse.
(da qui). Ecco la mia migliore interpretazione:
L’Admin API, talvolta indicata anche come JSON API, può essere utilizzata quando si desidera effettuare chiamate API per interagire con un forum Discourse e:
- tali chiamate non richiedono alcuna autenticazione, oppure
- tali chiamate richiedono autenticazione, ma si ha il controllo diretto anche del forum Discourse, quindi è possibile generare manualmente chiavi API che il forum e/o l’app separata possono utilizzare per effettuare le chiamate API.
La User API, invece, è pensata per quando si desidera interagire con un forum (o più forum) Discourse, le interazioni richiedono autenticazione e non si ha il controllo del forum (o dei forum) con cui si desidera interagire.
Un altro modo per dirlo: l’Admin API è per quando si controlla il forum con cui si interagisce, mentre la User API è per quando non si controlla il forum.
È corretto?
Ad esempio, la descrizione di @david qui afferma che l’Admin API non è destinata all’uso con client JavaScript. Tuttavia, ritengo che sia corretto utilizzare l’Admin API con client JavaScript, purché il proprietario dell’app che utilizza tali client JavaScript controlli anche il forum (cioè, il proprietario dell’app separata è lo stesso del proprietario del forum). Giusto?
Credo che sia così. Se si desidera effettuare chiamate all’Admin API relative a un sito Discourse da un’app separata, credo sia possibile farlo lato server (da un backend). Se non si effettua da un backend, ma direttamente dal client, si potrebbero incontrare restrizioni CORS. In tal caso, è possibile aggiungere il dominio dell’app separata alla whitelist in admin/site_settings/security/ → “cors origins”.
Di seguito ho incluso ulteriori dettagli su come funzionano queste API. Un’altra domanda che mi rimane: quando si imposta una chiave API per l’Admin API, quando è appropriato utilizzare “Tutti gli utenti” come livello utente?
Ulteriori dettagli:
L'Admin API
Le basi
Questa è l’API descritta su docs.discourse.org. Talvolta indicata come JSON API.
Interagendo con gli endpoint di questa API, è possibile fare praticamente tutto ciò che si può fare direttamente su un sito Discourse, utilizzando il metodo descritto qui.
Alcuni endpoint richiedono autenticazione. Ad esempio, se si desidera utilizzare l’API per recuperare i dettagli di un gruppo specifico (endpoint: [your-forum]/groups/[group-name].json), ma quel gruppo è visibile solo ai suoi membri, allora è necessario effettuare la chiamata all’endpoint “a nome di” uno dei membri.
Per effettuare la chiamata API con la corretta autenticazione, è necessario generare una chiave API in [your-forum]/admin/api → Nuova chiave API, selezionando per tale chiave il livello utente “Singolo utente” e scegliendo un utente autorizzato a visualizzare la risorsa (ad esempio, informazioni su un gruppo).
Quando si effettua quindi la chiamata API, si includono le intestazioni: la chiave come Api-Key e il nome utente dell’utente come Api-Username.
C’è anche l’opzione, durante l’impostazione della chiave API, di scegliere “Tutti gli utenti”. Come ho chiesto sopra, non sono sicuro di quando sia appropriato farlo rispetto, ad esempio, alla scelta di un singolo utente che sia anche Amministratore.
Quando usarla
È possibile utilizzare l’Admin API “dall’interno” della propria app Discourse. Quindi è possibile interagire con l’Admin API: (i) dalla dashboard Modifica CSS/HTML per ogni tema in [your-forum]/admin/customize, (ii) da un tema integrato nel proprio sito Discourse e (iii) da un plugin integrato nel proprio sito Discourse.
È inoltre possibile utilizzare l’Admin API da un’app separata, se si controlla il forum Discourse in modo da poter generare manualmente le chiavi API che l’app separata utilizzerà.
Come ho chiesto sopra, questa è l’interpretazione che spero di confermare.
La User API
I dettagli di questa API sono descritti qui: User API keys specification
Credo che la User API esista perché l’Admin API non è destinata a essere utilizzata come API generale accessibile a qualsiasi sito o app separato dal proprio forum.
Per essere chiari su questo: ci sono due scenari diversi in cui un’app separata potrebbe interagire con il proprio forum Discourse:
Scenario 1: Nessuna connessione diretta: Uno sviluppatore non collegato al forum Discourse crea un’app che interagisce con il forum. Ad esempio, uno sviluppatore che non è l’amministratore del forum o comunque non è collegato all’amministratore del forum desidera creare un’app che interroghi vari siti Discourse per ottenere alcuni dati o informazioni da essi.
In questo scenario, l’amministratore del forum Discourse non genererà manualmente una chiave API da fornire allo sviluppatore non collegato. Quindi l’Admin API non è appropriata.
Quindi, proprio come molti siti come YouTube hanno un’API che gli sviluppatori di terze parti possono utilizzare per interagire con YouTube nelle app che creano, la User API di Discourse è un modo per le app di terze parti di interagire con il proprio forum, consentendo ai client (desktop, telefoni cellulari) che utilizzano tali app di generare una chiave API che concede loro un accesso limitato al forum.
Scenario 2: Un’app direttamente collegata: L’amministratore di un forum (o uno sviluppatore collegato all’amministratore) è connesso a un’app separata con cui l’amministratore desidera che il forum interagisca.
Ad esempio, forse un amministratore desidera che esista un’app separata con funzionalità non Discourse e desidera che vi sia una sovrapposizione tra gli utenti dell’app separata e quelli del forum. In questo caso, l’amministratore può effettivamente generare direttamente (manualmente tramite la dashboard di amministrazione del forum) le chiavi API e fornirle all’app separata da utilizzare, in modo che l’app separata possa utilizzare l’Admin API.