Je cherche un moyen d’obtenir une liste définitive des points d’accès API disponibles dans mon instance Discourse. Il peut parfois être difficile de savoir quelles API sont à ma disposition lorsque je cherche à intégrer une plateforme.
5 « J'aime »
Je ne pense pas que ce soit techniquement possible. Discourse n’a pas de route de découverte d’API (par exemple, quelque chose de similaire à la route WordPress /wp-json). La chose la plus proche dont je sois conscient est la documentation sur https://docs.discourse.org/.
Pour les intégrations qui ne sont pas couvertes par la documentation, le moyen le plus rapide de savoir si elles sont réalisables est probablement de demander ici comment atteindre un objectif spécifique. La règle générale avec l’API est que tout ce qui peut être fait via l’interface utilisateur de Discourse peut également être fait via l’API.
9 « J'aime »
J’apprécie votre réponse, Simon ! Je connais docs.discourse.org (qui, assez drôlement, ne sont pas les docs officiels mais les spécifications de l’API).
Je connais également l’utilisation de la console de mon navigateur pour capturer des requêtes, ainsi que la lecture des fichiers routes.rb.
Comme vous pouvez l’imaginer, cependant, les deux options ci-dessus sont assez fastidieuses et pas très conviviales. Pour ceux d’entre nous qui cherchent à construire rapidement des intégrations approfondies – surtout si nous avons d’autres équipes dans notre entreprise ou des fournisseurs tiers qui veulent s’intégrer… leur dire de faire les choses ci-dessus a eu une réponse terriblement médiocre.
Bien que je sois conscient de la flexibilité des capacités de Discourse, le développement sur la plateforme ou l’intégration avec celle-ci est une bataille difficile, pour le moins qu’on puisse dire. En dernier recours, j’espérais qu’il existait un moyen programmatique d’agréger les API publiques.
7 « J'aime »
La source définitive, autre que la source, est de faire de l’ingénierie inverse de l’API Discourse.
Tout ce que vous pouvez faire sur le frontend, vous pouvez le faire avec l’API. Il y a très peu de choses que vous ne pouvez faire qu’avec l’API.
3 « J'aime »
Pouvez-vous clarifier ce que vous entendez par là un peu plus ?
Bien que le point de Simon concernant le fait que ceux-ci ne couvrent pas les API implémentées par des extensions de Discourse (par exemple, les plugins) soit valable, cette documentation est officielle dans le sens où nous la maintenons.
Cela ne veut pas dire que nous n’avons pas une marge d’amélioration considérable en ce qui concerne la documentation de l’API côté serveur, et l’API elle-même, mais je voulais mieux comprendre vos commentaires sur la documentation qui existe déjà.
1 « J'aime »
Absolument ! C’est probablement plus que ce que vous aviez demandé 
Je pense que vous conservez votre documentation officielle sur les produits ici, n’est-ce pas ?
Je dirais que la nuance est que les spécifications de l’API sont un sous-ensemble de la documentation. J’oublie donc toujours et cela me surprend un instant lorsque j’oriente quelqu’un vers docs.discourse.org et que j’oublie que ce lien ne mène pas à la documentation de Discourse… il mène à un ensemble limité de spécifications d’API.
Alors je leur dis une version de :
Merci de nous avoir rencontrés aujourd’hui, je suis ravi que vous souhaitiez voir le type d’expérience que vous pouvez créer pour nos utilisateurs en utilisant la nouvelle communauté Netwrix !
La documentation se trouve en fait sur https://meta.discourse.org/c/documentation/10.
docs.discourse.org n’est pas vraiment leur documentation, mais leurs spécifications d’API. Je sais que vous avez posé des questions sur l’intégration avec la nouvelle communauté que nous construisons. Malheureusement, je n’ai pas de page à vous indiquer qui montre toutes les fonctionnalités que Discourse offre, mais vous pouvez aller sur docs.discourse.org pour avoir une idée de ce qui est possible.
Ce que je fais dans ce scénario, car je ne peux pas leur donner une liste définitive des points d’accès existants, c’est que je leur dis simplement : « Supposez que tout ce que vous pouvez imaginer est possible. Je vais sortir et voir ce que Discourse peut faire, et nous réduirons à partir de là si nécessaire. »
Mais ce serait vraiment bien si toutes les API étaient listées dans les spécifications, n’est-ce pas ?
Plus de contexte…
Ce serait étrange si j’achetais une voiture et qu’on me donnait une feuille de caractéristiques et que je demandais : « Génial ! Est-ce tout alors ? »
« Eh bien, non… mais si vous regardez sous le capot et suivez le câblage 12V et les colliers de serrage autour du moteur, vous devriez pouvoir voir à quoi ils se connectent et faire une ingénierie inverse de ce qu’il fait d’autre. »
Bien sûr, le mécanicien/développeur/personne techniquement douée dans ce scénario peut le faire. Mais pas tout le monde 
De plus, même en tant que développeur, je ne veux pas :
- Apprendre Ruby pour voir où les routes pourraient exister
- Faire une ingénierie inverse de tous les fichiers routes.rb pour avoir une idée des points d’accès disponibles
- Affiner davantage cette ingénierie inverse pour déterminer les entrées dont ils ont besoin, quelle est la structure objet de la sortie
- Vérifier quels plugins j’ai aussi
- Répéter sur leurs fichiers routes.rb (je pense ? Je ne connais pas Ruby, donc je ne suis pas vraiment sûr)
- … et 6 mois plus tard, entre mon travail et cela, j’ai une réponse.
Je dis tout cela affectueusement — il n’y a pas aujourd’hui de plateforme qui puisse rivaliser avec les capacités de la plateforme Discourse. Point final. C’est le produit le plus solide, le plus puissant, le plus flexible et le plus rentable du marché, et il est bien au-dessus de la concurrence.
Ses lacunes ne sont pas sa robustesse, sa puissance et sa flexibilité. En fait, ce sont certains des plus grands avantages de Discourse que les produits concurrents auront du mal, voire échoueront, à imiter.
- Ce n’est pas que ses API ne sont pas géniales — c’est qu’il est difficile de les trouver.
- Ce ne sont pas les panneaux d’administration avec de nombreuses options qui rendent l’adoption difficile, mais le manque d’éducation et les noms de paramètres d’administration comme
First post onlyqui sont au mieux ambigus. - Ce n’est pas son implémentation robuste mais simple (et parfaite !) d’une structure d’outil communautaire de catégories, de sujets et de balises, mais que l’information n’existe pas pour éduquer et inspirer les utilisateurs qu’il n’a pas à être une catégorie, mais un blog, ou un tableau d’annonces de produits, ou un portail d’idées… et qu’ils n’ont pas à être des sujets mais peuvent être des blogs, des annonces de produits et des idées.
C’est la seule chose qui manque à Discourse en tant que produit pour moi : la finition — les détails finaux.
9/10, achèterais à nouveau.
7 « J'aime »
OK, je pense que je comprends mieux, merci.
Ce qui suit sont mes propres opinions – je ne les ai pas soumises à des personnes plus compétentes que moi, donc je pourrais être corrigé sur certaines choses que je me trompe ici.
Notre documentation d’histoire évolue également. Nous avons fait des progrès significatifs, mais il y a encore un long chemin à parcourir. Permettez-moi d’essayer de résumer un peu.
Premièrement, comme une sorte de modèle mental de niveau supérieur, je décrirais les choses comme suit :
- Notre point d’entrée principal pour la documentation est ici, comme vous l’avez souligné : Documentation - Discourse Meta
- Pour la documentation développeur, elle est ici, ou peut-être encore mieux, ici : Introduction to Discourse Development
- La documentation de l’API est un sous-ensemble de la documentation développeur, et se trouve ici : https://docs.discourse.org/
- Pour la documentation développeur, elle est ici, ou peut-être encore mieux, ici : Introduction to Discourse Development
J’appellerais la documentation de l’API des docs plutôt que des spécifications, mais je suis d’accord qu’elle reste un sous-ensemble de notre documentation développeur. L’URL de cette documentation est étrange… il serait plus logique que notre documentation complète y réside ou que ce soit une redirection vers https://meta.discourse.org/c/documentation/10, et qu’il y ait un panneau indicateur clair depuis Introduction to Discourse Development vers la documentation de l’API.
Notre documentation développeur fait elle-même l’objet d’améliorations. L’historique des commits ici raconte probablement la meilleure histoire de l’effort consacré jusqu’à présent : Commits · discourse/discourse-developer-docs · GitHub
La documentation de l’API pourrait être décrite comme incomplète, mais nous avons du travail à faire pour mettre de l’ordre dans notre histoire ici. Dans le passé, nous indiquions de “rétro-concevoir l’API”, mais je suis d’accord que ce n’est pas une bonne approche. C’est bien pour le piratage à vos risques et périls, mais il peut y avoir des cas où les points de terminaison non listés ici feraient probablement mieux de ne pas en dépendre.
L’API côté serveur est principalement destinée à être consommée par notre application frontend. Sur le frontend, nous fournissons une API JavaScript qui serait une meilleure interface à consommer car elle peut masquer les changements apportés au backend : Using the JS API
Alors, quelles garanties de stabilité pouvons-nous faire concernant notre API backend ?
Je pense que c’est une responsabilité que ces documents d’API devraient aborder. Idéalement, ce qui y est documenté est un sous-ensemble de tous les points de terminaison que nous prenons en charge, mais un sous-ensemble intentionnel que nous visons à prendre en charge pour d’autres qui créent des intégrations, tandis que les choses non listées ici sont intentionnellement non documentées comme étant des choses uniquement destinées à notre frontend, qui peuvent changer sans préavis.
Idéalement (dans mon esprit), la documentation serait intégrée au code source d’une manière telle que les documents eux-mêmes soient testés, extensibles avec des plugins, servis par l’application elle-même afin qu’ils soient synchronisés avec l’instance qui est documentée – de cette façon, vous pourriez consulter la documentation de l’API pour un site donné et voir la documentation de la version qu’il exécute, avec tous les plugins réellement installés et activés.
Je sais que d’autres en interne ont eu de nombreuses discussions sur d’autres idées pour améliorer notre histoire d’API côté serveur.
Nous n’avons pas encore pu prioriser grand-chose dans cet espace, car notre objectif principal en matière d’expérience développeur ces deux dernières années a été la modernisation de notre frontend.
Je ne suis pas sûr quand cela est susceptible de changer, mais nous garderons un œil sur les petites choses que nous pouvons faire en cours de route pour continuer à améliorer l’histoire de l’API côté serveur. S’il y a des questions spécifiques qui se posent, nous pourrons peut-être les utiliser comme un élan pour apporter des améliorations plus ciblées en attendant.
5 « J'aime »
Les garanties de stabilité devraient être abordées par un versionnement d’API simple.
Ce sujet ne porte pas sur l’emplacement de la documentation, mais sur la manière dont l’API est documentée. Ce qui manque, c’est un format standardisé et lisible par machine comme OpenAPI.
Cette absence, ainsi que le manque de versionnement, rendent le travail d’intégration plus difficile et plus fragile qu’il ne devrait l’être. Même un schéma OpenAPI de base pour les points d’accès documentés serait très utile.
3 « J'aime »
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.
10 « J'aime »
Je pense qu’il est tout à fait raisonnable que le changement prenne du temps. J’ai dirigé les relations avec les développeurs dans ma dernière entreprise et, mon Dieu… il a fallu plus de deux ans pour que nos API atteignent un état amélioré. Tant de choses complexes à considérer (et l’ingénierie détestait l’idée de créer un point de terminaison stable qui ne pourrait pas changer !)\n\nJe pense cependant que des changements plus petits peuvent se produire au fil du temps et dans un délai plus court. Je n’ai pas regardé comment vos routes (ou comment les routes en Ruby) sont définies, je l’avoue, mais je suppose que certaines choses faciles à faire pourraient être gérées assez facilement. Par exemple :\n\nJe ne peux pas parler pour tout le monde, mais j’ai l’impression que même si les points de terminaison existent dans votre spécification d’API actuelle — même si vous n’aviez pas de descriptions et d’exemples, et même si le modèle de réponse était fluide — ce serait une énorme victoire. Savoir simplement que quelque chose existe est parfois la moitié de la bataille.
5 « J'aime »
La documentation de l’API est au format 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 « J'aime »
Je dois honteusement admettre que je ne l’avais jamais remarqué…
Merci @blake de l’avoir signalé.
2 « J'aime »