J’espère clarifier quand et dans quel but les deux systèmes d’authentification de l’API Discourse fonctionnent.
(de ici). Voici ma meilleure compréhension :
L’API Admin, parfois aussi appelée API JSON, peut être utilisée lorsque vous souhaitez effectuer des appels API pour interagir avec un forum Discourse et que :
- ces appels ne nécessitent aucune authentification, ou
- ces appels nécessitent une authentification, mais vous avez également un contrôle direct sur le forum Discourse, ce qui vous permet de générer manuellement des clés API que votre forum et/ou l’application séparée peuvent utiliser pour effectuer les appels API.
L’API Utilisateur, quant à elle, est destinée aux cas où vous souhaitez interagir avec un forum Discourse (ou plusieurs), que ces interactions nécessitent une authentification, et que vous ne contrôlez pas le forum (ou les forums) avec lesquels vous souhaitez interagir.
Autrement dit : l’API Admin est pour lorsque vous contrôlez le forum avec lequel vous interagissez, et l’API Utilisateur est pour lorsque vous ne contrôlez pas le forum.
Est-ce exact ?
Par exemple, la description de @david ici indique que l’API Admin n’est pas destinée à être utilisée avec des clients JavaScript. Mais je pense qu’il est acceptable d’utiliser l’API Admin avec des clients JavaScript tant que le propriétaire de l’application utilisée par ces clients JavaScript contrôle également le forum. (c’est-à-dire que le propriétaire de l’application séparée est le même que celui du forum.) N’est-ce pas ?
Je suppose que c’est ainsi que cela fonctionne. Si vous souhaitez effectuer des appels à l’API Admin concernant un site Discourse depuis une application séparée, alors je pense que vous pouvez effectuer ces appels côté serveur (depuis un backend). Si vous ne les effectuez pas depuis un backend – mais depuis le côté client, vous risquez de rencontrer des restrictions CORS. Dans ce cas, vous pouvez ajouter le domaine de l’application séparée à la liste blanche dans admin/site_settings/security/ → “cors origins”.
Ci-dessous, j’ai également inclus plus de détails sur le fonctionnement de ces API. Une autre question que je me pose encore : lorsque vous définissez une clé API pour l’API Admin, quand est-il approprié d’utiliser « Tous les utilisateurs » comme niveau utilisateur ?
Détails supplémentaires :
L'API Admin
Les bases
Il s’agit de l’API décrite sur docs.discourse.org. Parfois appelée API JSON.
En interagissant avec les points de terminaison de cette API, vous pouvez faire à peu près tout ce que vous pourriez faire directement sur un site Discourse, en utilisant la méthode décrite ici.
Certains points de terminaison nécessitent une authentification. Par exemple, si vous souhaitez utiliser l’API pour récupérer les détails d’un groupe particulier (point de terminaison : [votre-forum]/groups/[nom-du-groupe].json), mais que ce groupe n’est visible que par ses membres, alors vous devrez effectuer l’appel au point de terminaison « au nom de » l’un des membres.
Pour effectuer l’appel API avec une authentification appropriée, vous devrez générer une clé API à l’adresse [votre-forum]/admin/api → Nouvelle clé API, en sélectionnant pour cette clé le niveau utilisateur « Utilisateur unique » et en choisissant un utilisateur autorisé à voir la ressource (tel que des informations sur un groupe).
Lorsque vous effectuez ensuite l’appel API, vous incluez les en-têtes : la clé sous Api-Key et le nom d’utilisateur de l’utilisateur sous Api-Username.
Il existe également l’option, lors de la définition de la clé API, de choisir « Tous les utilisateurs ». Comme mentionné dans ma question ci-dessus, je ne suis pas sûr de savoir quand c’est approprié par rapport, par exemple, à choisir un seul utilisateur et à ce que cet utilisateur soit administrateur.
Quand l’utiliser
Vous pouvez utiliser l’API Admin « depuis » votre application Discourse. Vous pouvez donc interagir avec l’API Admin : (i) depuis le tableau de bord Modifier CSS/HTML pour chaque thème sous [votre-forum]/admin/customize, (ii) depuis un thème que vous intégrez à votre site Discourse, et (iii) depuis un plugin que vous intégrez à votre site Discourse.
Vous pouvez également utiliser l’API Admin depuis une application séparée, si vous contrôlez le forum Discourse de sorte que vous puissiez, via le forum, générer manuellement les clés API que l’application séparée utilisera.
Comme mentionné dans ma question ci-dessus, c’est la compréhension que j’espère confirmer.
L'API Utilisateur
Les détails de cette API sont décrits ici : User API keys specification
Je pense que l’API Utilisateur existe parce que l’API Admin n’est pas destinée à être utilisée comme une API générale accessible à n’importe quel site ou application séparé de votre forum.
Pour être clair à ce sujet : il existe deux scénarios différents où une application séparée pourrait interagir avec votre forum Discourse :
Scénario 1 : Aucune connexion directe : Un développeur non connecté au forum Discourse crée une application qui interagit avec le forum. Par exemple, un développeur qui n’est pas l’administrateur du forum ou autrement connecté à l’administrateur du forum souhaite créer une application qui interroge divers sites Discourse pour obtenir des faits à leur sujet ou des informations en retour.
Dans ce scénario, l’administrateur du forum Discourse ne générera pas manuellement une clé API à remettre au développeur non connecté. L’API Admin n’est donc pas appropriée.
Ainsi, tout comme de nombreux sites comme YouTube ont une API que les développeurs tiers peuvent utiliser pour interagir avec YouTube sur les applications qu’ils créent, l’API Utilisateur Discourse est un moyen pour les applications tierces d’interagir avec votre forum en permettant aux clients (ordinateurs de bureau, téléphones mobiles) utilisant les applications de générer une clé API qui leur donne un accès limité au forum.
Scénario 2 : Une application directement connectée : L’administrateur d’un forum (ou un développeur connecté à l’administrateur) est connecté à une application séparée avec laquelle l’administrateur souhaite interagir avec le forum.
Par exemple, un administrateur souhaite peut-être qu’il existe une application séparée avec des fonctionnalités non-Discourse, et il/elle souhaite qu’il y ait un chevauchement entre les utilisateurs de l’application séparée et du forum. Dans ce cas, l’administrateur peut en fait générer directement (manuellement via le tableau de bord d’administration du forum) les clés API et les fournir à l’application séparée à utiliser, afin que l’application séparée puisse utiliser l’API Admin.